@lobehub/editor 4.29.1 → 4.29.2

package/README.md

@@ -43,6 +43,7 @@ A modern, extensible rich text editor built on Meta's Lexical framework with dua
   - [Plugin Features](#plugin-features)
 - [📖 API Reference](#-api-reference)
   - [Editor Kernel](#editor-kernel)
+  - [LiteXML and Node IDs](#litexml-and-node-ids)
   - [Plugin System](#plugin-system)
 - [🛠️ Development](#️-development)
   - [Setup](#setup)
@@ -353,6 +354,91 @@ interface IEditor {
 }
 ```
 
+### LiteXML and Node IDs
+
+Each content node's durable public ID is stored at `$.properties.nodeId`; LiteXML exposes the same value as its `id` attribute. These IDs are opaque and independent of Lexical runtime keys. Newly generated IDs use 10 lowercase base-36 characters, with cryptographic randomness when the runtime provides it. Existing imported IDs remain unchanged unless they are invalid or collide with another content node. Read IDs from an exported LiteXML snapshot before using them as an operation's `id`, `beforeId`, or `afterId`. Importing JSON with `keepId: true` preserves valid, nonconflicting IDs; `keepId: false` assigns fresh IDs. The literal `root` is reserved for document-boundary `beforeId` and `afterId` insertion anchors. Imported content IDs that trim to `root` are repaired with fresh IDs.
+
+Yjs v1 reconciles collisions created when disconnected clients import different nodes with the same explicit ID. Valid LiteXML review before/after pairs stay together; otherwise, the node with the smallest shared Yjs identity in deterministic order keeps the ID. Other nodes receive the same deterministic repair IDs on every client, and the repair is excluded from user undo history.
+
+An ID names a **logical content node**, not one physical Lexical object. A pending LiteXML modification can contain before and after representations with the same ID. Lookup addresses the active after representation; pending removals are absent from the active view. Accepting or rejecting a change keeps the surviving logical ID, while an independent copy or split receives a new ID. Review wrappers and the document root are not addressable. Without `LitexmlPlugin`, `CommonPlugin` uses a plain tree view with no review rules.
+
+Yjs external snapshots repair duplicate explicit IDs deterministically. Replaying the same malformed snapshot therefore keeps the repaired IDs and does not rewrite the shared document again.
+
+Use `$getNodeById` only synchronously inside a Lexical read or update. It returns a Lexical node in that context, so do not retain the result across updates. A historical `EditorState.read` must receive `{ editor: lexicalEditor }` to select that editor's identity policy. Invalid or unknown IDs return `null`.
+
+For application code outside a Lexical callback, `CommonPlugin` registers `INodeIdentityService`. Its `getNodeById` returns detached, immutable `{ id, type, textContent }` metadata from the last committed state. `textContent` is the native Lexical text for that node; an outer review container can include both pending sides. Use a LiteXML or Markdown export when you need the projected document text. `subscribe` signals committed updates and identity-policy changes; call `getNodeById` in the listener to refresh the metadata. Unsubscribe when the consumer unmounts. After the editor is destroyed, a retained service returns `null`.
+
+The same `$getNodeById`, `$getNodeId`, and `INodeIdentityService` exports are available from `@lobehub/editor/headless`; headless consumers can use that entry without importing the browser bundle.
+
+`$getNodeById` walks the active tree in O(N) time so pending edits and historical reads use the exact Lexical state in the callback. The service builds a key-only index once per committed `EditorState` in O(N) time, then resolves later IDs in O(1) before extracting native `textContent` (which can itself traverse a subtree). The [identity benchmark](scripts/benchmark-node-identity.ts) records diagnostic timings; it does not set CI timing thresholds.
+
+```typescript
+import { $getNodeById, INodeIdentityService, type IEditor } from '@lobehub/editor';
+
+function inspectNode(kernel: IEditor, id: string) {
+  // CommonPlugin must be registered and the editor initialized.
+  const identity = kernel.requireService(INodeIdentityService);
+  const snapshot = identity?.getNodeById(id); // Safe to keep outside Lexical callbacks.
+
+  const lexicalEditor = kernel.getLexicalEditor();
+  lexicalEditor?.getEditorState().read(
+    () => {
+      const node = $getNodeById(id); // Active LiteXML representation, if installed.
+      console.log(node?.getType());
+    },
+    { editor: lexicalEditor },
+  );
+
+  return snapshot;
+}
+```
+
+`HeadlessEditor.applyLiteXMLBatchWithResults(operations)` returns one result per input operation, in array order. `status: 'applied'` means the change is staged in the editor; pending review diffs still need a separate accept or reject action. A `modify` operation containing multiple LiteXML fragments applies all of its targets or none: missing targets, malformed fragments, incompatible list, table, or inline/block structure, repeated target IDs, and ancestor/descendant target pairs fail that operation before it changes the document. Distinct sibling targets can be modified together. Failed operations include a reason, and later independent operations still run:
+
+```typescript
+import { createHeadlessEditor } from '@lobehub/editor/headless';
+
+const editor = createHeadlessEditor();
+editor.hydrateMarkdown('- first\n- second');
+const { litexml } = editor.export({ litexml: true });
+const targetId = /<li id="([^"]+)"/.exec(litexml!)?.[1];
+if (!targetId) throw new Error('No list item ID found in LiteXML');
+
+const operations = [
+  { action: 'remove' as const, id: targetId },
+  { action: 'remove' as const, id: 'unknown-id' },
+];
+
+const results = await editor.applyLiteXMLBatchWithResults(operations);
+// results[1] has status: 'failed' and a reason.
+editor.destroy();
+```
+
+For a direct `IEditor` integration, dispatch `LITEXML_MODIFY_WITH_RESULTS_COMMAND` instead of calling the headless wrapper:
+
+```typescript
+import type { IEditor } from '@lobehub/editor';
+import { LITEXML_MODIFY_WITH_RESULTS_COMMAND } from '@lobehub/editor/litexml-commands';
+
+function applyWithResults(kernel: IEditor) {
+  // The editor is already initialized with LiteXML and has a loaded document.
+  const currentLiteXml = kernel.getDocument('litexml') as unknown as string;
+  const targetId = /<li id="([^"]+)"/.exec(currentLiteXml)?.[1];
+  if (!targetId) throw new Error('No list item ID found in LiteXML');
+
+  kernel.dispatchCommand(LITEXML_MODIFY_WITH_RESULTS_COMMAND, {
+    operations: [
+      { action: 'remove', id: targetId },
+      { action: 'remove', id: 'unknown-id' },
+    ],
+    onResults: (batchResults) => {
+      const failed = batchResults.filter((result) => result.status === 'failed');
+      console.log(failed);
+    },
+  });
+}
+```
+
 ### Plugin System
 
 #### Creating Custom Plugins

package/es/editor-kernel/index.d.ts

@@ -2,5 +2,5 @@ import DataSource from "./data-source.js";
 import "../types/index.js";
 import { $closest, $closestNodeType, $getNearestNodeFromDOMNode as $getNearestNodeFromDOMNode$1, $getNodeFromDOMNode, DOM_DOCUMENT_FRAGMENT_TYPE, DOM_DOCUMENT_TYPE, DOM_ELEMENT_TYPE, DOM_TEXT_TYPE, EDITOR_THEME_KEY, assert, compareNodeOrder, createEmptyEditorState, genServiceId, generateEditorId, getKernelFromEditor, getKernelFromEditorConfig, getNodeKeyFromDOMNode, getParentElement, isDOMNode, isDocumentFragment, moment, noop, reconcileDecorator, registerEditorKernel, unregisterEditorKernel } from "./utils.js";
 import { HOVER_COMMAND } from "./event.js";
-import { resetRandomKey as resetRandomKey$1 } from "lexical";
-export { $closest, $closestNodeType, $getNearestNodeFromDOMNode$1 as $getNearestNodeFromDOMNode, $getNodeFromDOMNode, DOM_DOCUMENT_FRAGMENT_TYPE, DOM_DOCUMENT_TYPE, DOM_ELEMENT_TYPE, DOM_TEXT_TYPE, DataSource, EDITOR_THEME_KEY, HOVER_COMMAND, assert, compareNodeOrder, createEmptyEditorState, genServiceId, generateEditorId, getKernelFromEditor, getKernelFromEditorConfig, getNodeKeyFromDOMNode, getParentElement, isDOMNode, isDocumentFragment, moment, noop, reconcileDecorator, registerEditorKernel, resetRandomKey$1 as resetRandomKey, unregisterEditorKernel };
+import { resetRandomKey } from "lexical";
+export { $closest, $closestNodeType, $getNearestNodeFromDOMNode$1 as $getNearestNodeFromDOMNode, $getNodeFromDOMNode, DOM_DOCUMENT_FRAGMENT_TYPE, DOM_DOCUMENT_TYPE, DOM_ELEMENT_TYPE, DOM_TEXT_TYPE, DataSource, EDITOR_THEME_KEY, HOVER_COMMAND, assert, compareNodeOrder, createEmptyEditorState, genServiceId, generateEditorId, getKernelFromEditor, getKernelFromEditorConfig, getNodeKeyFromDOMNode, getParentElement, isDOMNode, isDocumentFragment, moment, noop, reconcileDecorator, registerEditorKernel, resetRandomKey, unregisterEditorKernel };

package/es/editor-kernel/index.js

@@ -2,7 +2,7 @@ import { HOVER_COMMAND, init_event } from "./event.js";
 import { $closest, $closestNodeType, $getNearestNodeFromDOMNode as $getNearestNodeFromDOMNode$1, $getNodeFromDOMNode, DOM_DOCUMENT_FRAGMENT_TYPE, DOM_DOCUMENT_TYPE, DOM_ELEMENT_TYPE, DOM_TEXT_TYPE, EDITOR_THEME_KEY, assert, compareNodeOrder, createEmptyEditorState, genServiceId, generateEditorId, getKernelFromEditor, getKernelFromEditorConfig, getNodeKeyFromDOMNode, getParentElement, init_utils, isDOMNode, isDocumentFragment, moment, noop, reconcileDecorator, registerEditorKernel, unregisterEditorKernel } from "./utils.js";
 import { Kernel, init_kernel } from "./kernel.js";
 import DataSource from "./data-source.js";
-import { resetRandomKey as resetRandomKey$1 } from "lexical";
+import { resetRandomKey } from "lexical";
 //#region src/editor-kernel/index.ts
 init_kernel();
 init_utils();
@@ -15,4 +15,4 @@ const Editor = { createEditor() {
 	return new Kernel();
 } };
 //#endregion
-export { $closest, $closestNodeType, $getNearestNodeFromDOMNode$1 as $getNearestNodeFromDOMNode, $getNodeFromDOMNode, DOM_DOCUMENT_FRAGMENT_TYPE, DOM_DOCUMENT_TYPE, DOM_ELEMENT_TYPE, DOM_TEXT_TYPE, DataSource, EDITOR_THEME_KEY, HOVER_COMMAND, assert, compareNodeOrder, createEmptyEditorState, Editor as default, genServiceId, generateEditorId, getKernelFromEditor, getKernelFromEditorConfig, getNodeKeyFromDOMNode, getParentElement, isDOMNode, isDocumentFragment, moment, noop, reconcileDecorator, registerEditorKernel, resetRandomKey$1 as resetRandomKey, unregisterEditorKernel };
+export { $closest, $closestNodeType, $getNearestNodeFromDOMNode$1 as $getNearestNodeFromDOMNode, $getNodeFromDOMNode, DOM_DOCUMENT_FRAGMENT_TYPE, DOM_DOCUMENT_TYPE, DOM_ELEMENT_TYPE, DOM_TEXT_TYPE, DataSource, EDITOR_THEME_KEY, HOVER_COMMAND, assert, compareNodeOrder, createEmptyEditorState, Editor as default, genServiceId, generateEditorId, getKernelFromEditor, getKernelFromEditorConfig, getNodeKeyFromDOMNode, getParentElement, isDOMNode, isDocumentFragment, moment, noop, reconcileDecorator, registerEditorKernel, resetRandomKey, unregisterEditorKernel };

package/es/headless/index.d.ts

@@ -1,8 +1,10 @@
 import { IDocumentOptions, IEditor, IPlugin } from "../types/kernel.js";
 import "../types/index.js";
-import { LITEXML_MODIFY_COMMAND } from "../plugins/litexml/command/symbols.js";
+import { LITEXML_MODIFY_COMMAND, LiteXmlOperationResult } from "../plugins/litexml/command/symbols.js";
 import "../plugins/litexml/command/index.js";
 import { FileListItem, ImageListItem, MediaLists, extractMediaFromEditorState } from "./extract-media-from-editor-state.js";
+import { $getNodeById, $getNodeId } from "../plugins/common/node/node-id.js";
+import { INodeIdentityService, NodeIdentitySnapshot } from "../plugins/common/service/i-node-identity-service.js";
 import { CommandPayloadType, SerializedEditorState, SerializedLexicalNode } from "lexical";
 //#region src/headless/index.d.ts
 type HeadlessDocumentType = 'json' | 'litexml' | 'markdown' | (string & object);
@@ -60,6 +62,7 @@ declare class HeadlessEditor {
   hydrateMarkdown(markdown: string, options?: IDocumentOptions): this;
   applyLiteXML(operation: HeadlessLiteXMLOperation | ReadonlyArray<HeadlessLiteXMLOperation>): Promise<this>;
   applyLiteXMLBatch(operations: CommandPayloadType<typeof LITEXML_MODIFY_COMMAND>): Promise<this>;
+  applyLiteXMLBatchWithResults(operations: CommandPayloadType<typeof LITEXML_MODIFY_COMMAND>): Promise<LiteXmlOperationResult[]>;
   export(options?: HeadlessEditorExportOptions): HeadlessEditorExport;
   exportState(options?: HeadlessEditorExportOptions): HeadlessEditorExport;
   destroy(): void;
@@ -67,4 +70,4 @@ declare class HeadlessEditor {
 }
 declare function createHeadlessEditor(options?: HeadlessEditorOptions): HeadlessEditor;
 //#endregion
-export { DEFAULT_HEADLESS_EDITOR_PLUGINS, type FileListItem, HeadlessDocumentType, HeadlessEditor, HeadlessEditorExport, HeadlessEditorExportOptions, HeadlessEditorHydrationInput, HeadlessEditorOptions, HeadlessLiteXMLBatchOperation, HeadlessLiteXMLInsertOperation, HeadlessLiteXMLOperation, HeadlessLiteXMLRemoveOperation, HeadlessLiteXMLReplaceOperation, type ImageListItem, type MediaLists, createHeadlessEditor, extractMediaFromEditorState };
+export { DEFAULT_HEADLESS_EDITOR_PLUGINS, type FileListItem, HeadlessDocumentType, HeadlessEditor, HeadlessEditorExport, HeadlessEditorExportOptions, HeadlessEditorHydrationInput, HeadlessEditorOptions, HeadlessLiteXMLBatchOperation, HeadlessLiteXMLInsertOperation, HeadlessLiteXMLOperation, HeadlessLiteXMLRemoveOperation, HeadlessLiteXMLReplaceOperation, type ImageListItem, type LiteXmlOperationResult, type MediaLists, createHeadlessEditor, extractMediaFromEditorState };

package/es/headless/index.js

@@ -1,6 +1,8 @@
+import { init_node_id } from "../plugins/common/node/node-id.js";
 import { init_utils, moment } from "../editor-kernel/utils.js";
 import Editor from "../editor-kernel/index.js";
-import { LITEXML_APPLY_COMMAND, LITEXML_INSERT_COMMAND, LITEXML_MODIFY_COMMAND, LITEXML_REMOVE_COMMAND } from "../plugins/litexml/command/symbols.js";
+import "../plugins/common/service/i-node-identity-service.js";
+import { LITEXML_APPLY_COMMAND, LITEXML_INSERT_COMMAND, LITEXML_MODIFY_COMMAND, LITEXML_MODIFY_WITH_RESULTS_COMMAND, LITEXML_REMOVE_COMMAND } from "../plugins/litexml/command/symbols.js";
 import { INodePlugin } from "../plugins/inode/plugin/index.js";
 import { MarkdownPlugin } from "../plugins/markdown/plugin/index.js";
 import { LitexmlPlugin } from "../plugins/litexml/plugin/index.js";
@@ -19,24 +21,11 @@ import { HeadlessCollapsiblePlugin } from "./collapsible-plugin.js";
 import { extractMediaFromEditorState } from "./extract-media-from-editor-state.js";
 //#region src/headless/index.ts
 init_utils();
-const getNumericId = (id) => {
-	if (typeof id !== "number" && typeof id !== "string") return null;
-	const numericId = Number(id);
-	return Number.isInteger(numericId) && numericId >= 0 ? numericId : null;
-};
-const findMaxSerializedId = (node) => {
-	if (!node || typeof node !== "object") return -1;
-	const record = node;
-	const ownMax = getNumericId(record.id) ?? -1;
-	if (!Array.isArray(record.children)) return ownMax;
-	return record.children.reduce((maxId, child) => Math.max(maxId, findMaxSerializedId(child)), ownMax);
-};
-const createSerializedId = (context) => String(context.nextId++);
-const createCodeChildrenFromLegacyCode = (code, context) => code.split("\n").flatMap((text, index, array) => {
+init_node_id();
+const createCodeChildrenFromLegacyCode = (code) => code.split("\n").flatMap((text, index, array) => {
 	const textNode = {
 		detail: 0,
 		format: 0,
-		id: createSerializedId(context),
 		mode: "normal",
 		style: "",
 		text,
@@ -45,18 +34,17 @@ const createCodeChildrenFromLegacyCode = (code, context) => code.split("\n").fla
 	};
 	if (index === array.length - 1) return textNode;
 	return [textNode, {
-		id: createSerializedId(context),
 		type: "linebreak",
 		version: 1
 	}];
 });
-const normalizeLegacyEditorDataNode = (node, context) => {
+const normalizeLegacyEditorDataNode = (node) => {
 	if (!node || typeof node !== "object") return node;
 	const record = node;
-	const children = Array.isArray(record.children) ? record.children.map((child) => normalizeLegacyEditorDataNode(child, context)) : record.children;
+	const children = Array.isArray(record.children) ? record.children.map((child) => normalizeLegacyEditorDataNode(child)) : record.children;
 	if (record.type === "code" && typeof record.code === "string" && !Array.isArray(children)) return {
 		...record,
-		children: createCodeChildrenFromLegacyCode(record.code, context),
+		children: createCodeChildrenFromLegacyCode(record.code),
 		direction: record.direction ?? "ltr",
 		format: record.format ?? "",
 		indent: record.indent ?? 0,
@@ -71,10 +59,9 @@ const normalizeLegacyEditorDataNode = (node, context) => {
 };
 const normalizeLegacyEditorData = (editorData) => {
 	const data = typeof editorData === "string" ? JSON.parse(editorData) : editorData;
-	const context = { nextId: findMaxSerializedId(data.root) + 1 };
 	return {
 		...data,
-		root: normalizeLegacyEditorDataNode(data.root, context)
+		root: normalizeLegacyEditorDataNode(data.root)
 	};
 };
 const extractSerializedCodeText = (children) => children.map((child) => {
@@ -157,6 +144,17 @@ var HeadlessEditor = class {
 		await moment();
 		return this;
 	}
+	async applyLiteXMLBatchWithResults(operations) {
+		let results;
+		if (!this.kernel.dispatchCommand(LITEXML_MODIFY_WITH_RESULTS_COMMAND, {
+			onResults: (operationResults) => {
+				results = operationResults;
+			},
+			operations
+		}) || !results) throw new Error("LiteXML batch result command is not registered.");
+		await moment();
+		return results;
+	}
 	export(options = {}) {
 		const snapshot = {
 			editorData: preserveSerializedCodeTextInEditorData(this.kernel.getDocument("json")),