@rtif-sdk/web 1.0.0

package/dist/block-renderer.js

@@ -0,0 +1,424 @@
+/**
+ * Block renderer registry — maps block types to DOM rendering functions.
+ *
+ * The renderer consults this registry when creating block elements to apply
+ * visual block-type effects (CSS classes, ARIA roles, data attributes).
+ * Built-in renderers handle heading, blockquote, code block, list item,
+ * horizontal rule, callout, image, and embed. Plugins can register custom
+ * renderers for additional block types.
+ *
+ * Additionally, the registry supports attr-based renderers that apply visual
+ * styling based on block attributes (e.g., alignment, indentation) regardless
+ * of block type.
+ *
+ * @module
+ */
+/**
+ * Create a new block renderer registry.
+ *
+ * @returns An empty registry ready for renderer registration
+ *
+ * @example
+ * ```ts
+ * const registry = createBlockRendererRegistry();
+ * registry.register('heading', headingRenderer);
+ * registry.registerAttrRenderer('align', alignAttrRenderer);
+ * ```
+ */
+export function createBlockRendererRegistry() {
+    const renderers = new Map();
+    const attrRenderers = new Map();
+    return {
+        register(blockType, renderer) {
+            renderers.set(blockType, renderer);
+        },
+        get(blockType) {
+            return renderers.get(blockType);
+        },
+        registerAttrRenderer(attrName, renderer) {
+            attrRenderers.set(attrName, renderer);
+        },
+        getAttrRenderer(attrName) {
+            return attrRenderers.get(attrName);
+        },
+        isAtomic(blockType) {
+            const renderer = renderers.get(blockType);
+            return renderer?.atomic === true;
+        },
+        applyToElement(el, block) {
+            const renderer = renderers.get(block.type);
+            if (renderer) {
+                renderer.apply(el, block);
+                if (renderer.atomic === true) {
+                    el.setAttribute('contenteditable', 'false');
+                }
+            }
+            if (block.attrs) {
+                for (const [key, value] of Object.entries(block.attrs)) {
+                    if (value == null)
+                        continue;
+                    const attrRenderer = attrRenderers.get(key);
+                    if (attrRenderer) {
+                        attrRenderer.apply(el, value);
+                    }
+                }
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Built-in block renderers
+// ---------------------------------------------------------------------------
+/**
+ * Clamp a heading level to the valid range 1-6.
+ *
+ * @param level - The raw level value from block attrs
+ * @returns A valid heading level between 1 and 6
+ */
+function clampHeadingLevel(level) {
+    if (typeof level !== 'number' || !Number.isFinite(level)) {
+        return 1;
+    }
+    return Math.max(1, Math.min(6, Math.floor(level)));
+}
+/**
+ * Built-in renderer for the `heading` block type.
+ *
+ * Adds CSS classes `rtif-heading` and `rtif-h{level}` where level comes
+ * from `block.attrs?.level` (defaults to 1, clamped to 1-6).
+ * Sets `data-heading-level`, `role="heading"`, and `aria-level` for
+ * accessibility.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'heading', attrs: { level: 2 }, ... }
+ * // Result: <div class="rtif-heading rtif-h2" role="heading" aria-level="2" data-heading-level="2">
+ * ```
+ */
+export const headingRenderer = {
+    apply(el, block) {
+        const level = clampHeadingLevel(block.attrs?.level);
+        el.classList.add('rtif-heading', `rtif-h${level}`);
+        el.setAttribute('data-heading-level', String(level));
+        el.setAttribute('role', 'heading');
+        el.setAttribute('aria-level', String(level));
+    },
+};
+/**
+ * Built-in renderer for the `blockquote` block type.
+ *
+ * Adds the `rtif-blockquote` CSS class to the block element.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'blockquote', ... }
+ * // Result: <div class="rtif-blockquote">
+ * ```
+ */
+export const blockquoteRenderer = {
+    apply(el) {
+        el.classList.add('rtif-blockquote');
+    },
+};
+/**
+ * Built-in renderer for the `code-block` block type.
+ *
+ * Adds the `rtif-code-block` CSS class. If `block.attrs?.language` is a
+ * non-empty string, sets a `data-language` attribute for syntax highlighting
+ * integration.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'code-block', attrs: { language: 'typescript' }, ... }
+ * // Result: <div class="rtif-code-block" data-language="typescript">
+ * ```
+ */
+export const codeBlockRenderer = {
+    apply(el, block) {
+        el.classList.add('rtif-code-block');
+        const language = block.attrs?.language;
+        if (typeof language === 'string' && language.length > 0) {
+            el.setAttribute('data-language', language);
+        }
+    },
+};
+/**
+ * Built-in renderer for the `list-item` block type.
+ *
+ * Adds CSS classes `rtif-list-item` and either `rtif-list-bullet` or
+ * `rtif-list-ordered` based on `block.attrs?.listStyle` (defaults to
+ * `'bullet'`). Sets `data-list-depth` from `block.attrs?.depth` (defaults
+ * to 0) and `role="listitem"` for accessibility.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'list-item', attrs: { listStyle: 'ordered', depth: 1 }, ... }
+ * // Result: <div class="rtif-list-item rtif-list-ordered" data-list-depth="1" role="listitem">
+ * ```
+ */
+export const listItemRenderer = {
+    apply(el, block) {
+        el.classList.add('rtif-list-item');
+        const listStyle = block.attrs?.listStyle;
+        if (listStyle === 'ordered') {
+            el.classList.add('rtif-list-ordered');
+        }
+        else {
+            el.classList.add('rtif-list-bullet');
+        }
+        const depth = block.attrs?.depth;
+        const depthValue = typeof depth === 'number' && Number.isFinite(depth) ? Math.max(0, Math.floor(depth)) : 0;
+        el.setAttribute('data-list-depth', String(depthValue));
+        el.setAttribute('role', 'listitem');
+    },
+};
+/**
+ * Built-in renderer for the `hr` (horizontal rule) block type.
+ *
+ * Adds the `rtif-hr` CSS class and sets `role="separator"` for
+ * accessibility. Marked as atomic — the block is non-editable.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'hr', ... }
+ * // Result: <div class="rtif-hr" role="separator" contenteditable="false">
+ * ```
+ */
+export const hrRenderer = {
+    apply(el) {
+        el.classList.add('rtif-hr');
+        el.setAttribute('role', 'separator');
+    },
+    atomic: true,
+};
+// ---------------------------------------------------------------------------
+// Phase 7 block renderers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a callout variant string from block attrs, defaulting to `"info"`.
+ *
+ * @param variant - The raw variant value from block attrs
+ * @returns A valid variant string
+ */
+function resolveCalloutVariant(variant) {
+    if (typeof variant === 'string' && variant.length > 0) {
+        return variant;
+    }
+    return 'info';
+}
+/**
+ * Built-in renderer for the `callout` block type.
+ *
+ * Creates a composite block with an icon span and a content container.
+ * The icon span has `contenteditable="false"` so it cannot be edited.
+ * The content div (class `rtif-callout-content`) is where inline spans
+ * are rendered, returned by {@link BlockRenderer.getContentContainer}.
+ *
+ * Supports a `variant` attribute (defaults to `"info"`) which is set as
+ * `data-variant` on the element. Implements {@link BlockRenderer.updateElement}
+ * for efficient in-place variant updates.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'callout', attrs: { variant: 'warning' }, ... }
+ * // Result:
+ * // <div class="rtif-callout" data-variant="warning">
+ * //   <span class="rtif-callout-icon" contenteditable="false"></span>
+ * //   <div class="rtif-callout-content">
+ * //     <!-- span elements rendered here -->
+ * //   </div>
+ * // </div>
+ * ```
+ */
+export const calloutRenderer = {
+    apply(el, block) {
+        const variant = resolveCalloutVariant(block.attrs?.variant);
+        el.classList.add('rtif-callout');
+        el.setAttribute('data-variant', variant);
+        const iconSpan = document.createElement('span');
+        iconSpan.className = 'rtif-callout-icon';
+        iconSpan.setAttribute('contenteditable', 'false');
+        el.appendChild(iconSpan);
+        const contentDiv = document.createElement('div');
+        contentDiv.className = 'rtif-callout-content';
+        el.appendChild(contentDiv);
+    },
+    getContentContainer(el) {
+        const content = el.querySelector('.rtif-callout-content');
+        // Defensive: if the content container is missing, fall back to the element itself
+        return content ?? el;
+    },
+    updateElement(el, block) {
+        const variant = resolveCalloutVariant(block.attrs?.variant);
+        el.setAttribute('data-variant', variant);
+        return true;
+    },
+};
+/**
+ * Built-in renderer for the `image` block type.
+ *
+ * Creates an atomic (non-editable) block containing an `<img>` element.
+ * Reads `src`, `alt`, `width`, and `height` from `block.attrs`.
+ * Sets `role="img"` on the block element for accessibility.
+ *
+ * Implements {@link BlockRenderer.updateElement} to efficiently update
+ * image attributes without full re-creation.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'image', attrs: { src: '/photo.jpg', alt: 'A photo', width: 400 }, ... }
+ * // Result:
+ * // <div class="rtif-image" role="img" contenteditable="false">
+ * //   <img src="/photo.jpg" alt="A photo" width="400">
+ * // </div>
+ * ```
+ */
+export const imageRenderer = {
+    apply(el, block) {
+        el.classList.add('rtif-image');
+        el.setAttribute('role', 'img');
+        const img = document.createElement('img');
+        applyImageAttrs(img, block);
+        el.appendChild(img);
+    },
+    updateElement(el, block) {
+        const img = el.querySelector('img');
+        if (!img) {
+            return false;
+        }
+        applyImageAttrs(img, block);
+        return true;
+    },
+    atomic: true,
+};
+/**
+ * Apply image-related block attrs to an `<img>` element.
+ *
+ * @param img - The `<img>` element to update
+ * @param block - The block containing image attrs (src, alt, width, height)
+ */
+function applyImageAttrs(img, block) {
+    const src = block.attrs?.src;
+    if (typeof src === 'string') {
+        img.setAttribute('src', src);
+    }
+    const alt = block.attrs?.alt;
+    if (typeof alt === 'string') {
+        img.setAttribute('alt', alt);
+    }
+    else {
+        img.removeAttribute('alt');
+    }
+    const width = block.attrs?.width;
+    if (typeof width === 'number' && width > 0) {
+        img.setAttribute('width', String(width));
+    }
+    else {
+        img.removeAttribute('width');
+    }
+    const height = block.attrs?.height;
+    if (typeof height === 'number' && height > 0) {
+        img.setAttribute('height', String(height));
+    }
+    else {
+        img.removeAttribute('height');
+    }
+}
+/**
+ * Built-in renderer for the `embed` block type.
+ *
+ * Creates an atomic (non-editable) block with a container div for embedded
+ * content (e.g., iframe, video, tweet). Sets `data-embed-url` from
+ * `block.attrs?.url`.
+ *
+ * @example
+ * ```ts
+ * // Block: { type: 'embed', attrs: { url: 'https://youtube.com/watch?v=abc' }, ... }
+ * // Result:
+ * // <div class="rtif-embed" data-embed-url="https://youtube.com/watch?v=abc" contenteditable="false">
+ * //   <div class="rtif-embed-container"></div>
+ * // </div>
+ * ```
+ */
+export const embedRenderer = {
+    apply(el, block) {
+        el.classList.add('rtif-embed');
+        const url = block.attrs?.url;
+        if (typeof url === 'string' && url.length > 0) {
+            el.setAttribute('data-embed-url', url);
+        }
+        const container = document.createElement('div');
+        container.className = 'rtif-embed-container';
+        el.appendChild(container);
+    },
+    atomic: true,
+};
+// ---------------------------------------------------------------------------
+// Built-in block attr renderers
+// ---------------------------------------------------------------------------
+/**
+ * Built-in attr renderer for the `align` block attribute.
+ *
+ * Sets `text-align` on the block element when the value is a string
+ * (e.g., "left", "center", "right", "justify").
+ *
+ * @example
+ * ```ts
+ * // Block: { attrs: { align: 'center' }, ... }
+ * // Result: <div style="text-align: center;">
+ * ```
+ */
+export const alignAttrRenderer = {
+    apply(el, value) {
+        if (typeof value === 'string') {
+            el.style.textAlign = value;
+        }
+    },
+};
+/**
+ * Built-in attr renderer for the `indent` block attribute.
+ *
+ * Sets `padding-left` on the block element based on the indent level.
+ * Each indent level adds 2em of padding. Values of 0 or less are ignored.
+ *
+ * @example
+ * ```ts
+ * // Block: { attrs: { indent: 2 }, ... }
+ * // Result: <div style="padding-left: 4em;">
+ * ```
+ */
+export const indentAttrRenderer = {
+    apply(el, value) {
+        if (typeof value === 'number' && value > 0) {
+            el.style.paddingLeft = `${value * 2}em`;
+        }
+    },
+};
+/**
+ * Register all built-in block renderers into a registry.
+ *
+ * Registers type renderers for: heading, blockquote, code-block, list-item,
+ * hr, callout, image, embed.
+ * Registers attr renderers for: align, indent.
+ *
+ * @param registry - The registry to populate
+ *
+ * @example
+ * ```ts
+ * const registry = createBlockRendererRegistry();
+ * registerBuiltinBlockRenderers(registry);
+ * ```
+ */
+export function registerBuiltinBlockRenderers(registry) {
+    registry.register('heading', headingRenderer);
+    registry.register('blockquote', blockquoteRenderer);
+    registry.register('code_block', codeBlockRenderer);
+    registry.register('list-item', listItemRenderer);
+    registry.register('hr', hrRenderer);
+    registry.register('callout', calloutRenderer);
+    registry.register('image', imageRenderer);
+    registry.register('embed', embedRenderer);
+    registry.registerAttrRenderer('align', alignAttrRenderer);
+    registry.registerAttrRenderer('indent', indentAttrRenderer);
+}
+//# sourceMappingURL=block-renderer.js.map

package/dist/block-renderer.js.map

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

package/dist/clipboard.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Clipboard handling — copy, cut, and paste for the RTIF web editor.
+ *
+ * Handles copy and cut with both plain text and RTIF JSON clipboard formats.
+ * Paste can be delegated to the content pipeline (skipPaste mode) or handled
+ * directly for plain text fallback.
+ *
+ * @see docs/spec/platform-requirements.md section 4 (Clipboard)
+ */
+import type { Document, Block, Selection, Operation } from '@rtif-sdk/core';
+/**
+ * Dependencies injected into {@link ClipboardHandler}.
+ *
+ * This keeps the clipboard module decoupled from the editor wiring and
+ * makes it testable in isolation.
+ *
+ * @example
+ * ```ts
+ * const deps: ClipboardDeps = {
+ *   getSelection: () => engine.state.selection,
+ *   getDoc: () => engine.state.doc,
+ *   dispatch: (ops) => engine.dispatch(ops),
+ *   isReadOnly: () => config.readOnly ?? false,
+ *   isComposing: () => compositionHandler.isComposing(),
+ *   generateBlockId: () => crypto.randomUUID(),
+ *   skipPaste: true,
+ * };
+ * ```
+ */
+export interface ClipboardDeps {
+    /** 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;
+    /** Whether the editor is in read-only mode. */
+    readonly isReadOnly: () => boolean;
+    /** Whether an IME composition session is active. */
+    readonly isComposing: () => boolean;
+    /** Generate a unique block ID for split_block operations. */
+    readonly generateBlockId: () => string;
+    /**
+     * When true, the paste event listener is not attached.
+     * The content pipeline handles paste instead.
+     * Default: false.
+     */
+    readonly skipPaste?: boolean;
+}
+/**
+ * Extract plain text from a document range defined by absolute offsets.
+ *
+ * Walks blocks and spans within `[start, end)`, inserting `'\n'` at
+ * virtual block boundaries. This is a pure function with no side effects.
+ *
+ * @param doc - The RTIF document
+ * @param start - Start offset (inclusive)
+ * @param end - End offset (exclusive)
+ * @returns The plain text string within the range
+ *
+ * @example
+ * ```ts
+ * const doc = {
+ *   version: 1,
+ *   blocks: [
+ *     { id: 'b1', type: 'text', spans: [{ text: 'hello' }] },
+ *     { id: 'b2', type: 'text', spans: [{ text: 'world' }] },
+ *   ],
+ * };
+ * extractPlainText(doc, 3, 8); // => 'lo\nwo'
+ * ```
+ */
+export declare function extractPlainText(doc: Document, start: number, end: number): string;
+/**
+ * Extract an RTIF block slice from a document range for clipboard serialization.
+ *
+ * Extracts blocks and spans within the absolute offset range `[start, end)`,
+ * preserving span marks and block attributes. The resulting blocks form a
+ * self-contained document fragment suitable for clipboard storage.
+ *
+ * @param doc - The RTIF document
+ * @param start - Start offset (inclusive)
+ * @param end - End offset (exclusive)
+ * @returns Array of extracted blocks with sliced spans
+ *
+ * @example
+ * ```ts
+ * const doc = {
+ *   version: 1,
+ *   blocks: [
+ *     {
+ *       id: 'b1', type: 'text',
+ *       spans: [
+ *         { text: 'hello ', marks: { bold: true } },
+ *         { text: 'world' },
+ *       ],
+ *     },
+ *   ],
+ * };
+ * const blocks = extractRtifSlice(doc, 0, 5);
+ * // => [{ id: 'b1', type: 'text', spans: [{ text: 'hello', marks: { bold: true } }] }]
+ * ```
+ */
+export declare function extractRtifSlice(doc: Document, start: number, end: number): Block[];
+/**
+ * Generate the RTIF operations needed to delete a selection range.
+ *
+ * For same-block selections, produces a single `delete_text`. For cross-block
+ * selections, composes `delete_text` and `merge_block` operations to remove
+ * all content within the range and merge the remaining fragments.
+ *
+ * The generated operations are designed to be dispatched as a single batch.
+ * After each operation, the merge point stays at the same absolute offset
+ * (`start`), which makes the sequencing correct.
+ *
+ * @param doc - The current RTIF document
+ * @param selection - The selection to delete
+ * @returns An array of operations (may be empty if selection is collapsed)
+ *
+ * @example
+ * ```ts
+ * // Single-block deletion
+ * const ops = deleteSelectionOps(doc, {
+ *   anchor: { offset: 2 },
+ *   focus: { offset: 5 },
+ * });
+ * // => [{ type: 'delete_text', offset: 2, count: 3 }]
+ * ```
+ */
+export declare function deleteSelectionOps(doc: Document, selection: Selection): Operation[];
+/**
+ * Handles copy, cut, and paste events on a contenteditable root element.
+ *
+ * Copy and cut write both `text/plain` and `application/x-rtif+json` to the
+ * clipboard. Paste handling can be delegated to the content pipeline by
+ * setting `skipPaste: true` in the deps.
+ *
+ * @example
+ * ```ts
+ * const handler = new ClipboardHandler(root, deps);
+ * handler.attach(); // start listening
+ * // ... later ...
+ * handler.detach(); // stop listening
+ * ```
+ */
+export declare class ClipboardHandler {
+    private readonly _root;
+    private readonly _deps;
+    private _copyHandler;
+    private _cutHandler;
+    private _pasteHandler;
+    constructor(root: HTMLElement, deps: ClipboardDeps);
+    /**
+     * Attach copy, cut, and (optionally) paste event listeners to the root element.
+     *
+     * When `skipPaste` is true in the deps, the paste listener is not attached.
+     * The content pipeline handles paste instead.
+     *
+     * @example
+     * ```ts
+     * handler.attach();
+     * ```
+     */
+    attach(): void;
+    /**
+     * Remove all clipboard event listeners from the root element.
+     *
+     * @example
+     * ```ts
+     * handler.detach();
+     * ```
+     */
+    detach(): void;
+    private _onCopy;
+    private _onCut;
+    private _onPaste;
+}
+//# sourceMappingURL=clipboard.d.ts.map

package/dist/clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../src/clipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAQ,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAclF;;;;;;;;;;;;;;;;;;GAkBG;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,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC;IAEnC,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC;IAEpC,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,MAAM,CAiDR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,KAAK,EAAE,CAoCT;AAoDD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,QAAQ,EACb,SAAS,EAAE,SAAS,GACnB,SAAS,EAAE,CA6Db;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,aAAa,CAA8C;gBAEvD,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa;IAKlD;;;;;;;;;;OAUG;IACH,MAAM,IAAI,IAAI;IAcd;;;;;;;OAOG;IACH,MAAM,IAAI,IAAI;IAmBd,OAAO,CAAC,OAAO;IAsBf,OAAO,CAAC,MAAM;IAuCd,OAAO,CAAC,QAAQ;CAqDjB"}