✨ feat: Optimize plugin command priority

Author: ilimei

src/editor-kernel/kernel.ts

@@ -1,5 +1,8 @@
 import EventEmitter from 'eventemitter3';
 import {
+  COMMAND_PRIORITY_CRITICAL,
+  CommandListener,
+  CommandListenerPriority,
   CommandPayloadType,
   DecoratorNode,
   LexicalCommand,
@@ -14,6 +17,7 @@ import defaultLocale from '@/locale';
 import DataSource from './data-source';
 import { registerEvent } from './event';
 import {
+  Commands,
   IEditor,
   IEditorKernel,
   IEditorPlugin,
@@ -228,4 +232,62 @@ export class Kernel extends EventEmitter implements IEditorKernel {
     }
     return translation;
   }
+
+  private _commands: Commands = new Map();
+  private _commandsClean: Map<LexicalCommand<unknown>, () => void> = new Map();
+
+  registerHighCommand<P>(
+    command: LexicalCommand<P>,
+    listener: CommandListener<P>,
+    priority: CommandListenerPriority,
+  ): () => void {
+    const lexicalEditor = this.editor;
+    if (!lexicalEditor) {
+      throw new Error('Editor is not initialized.');
+    }
+    const commandsMap = this._commands;
+
+    if (!commandsMap.has(command)) {
+      commandsMap.set(command, [new Set(), new Set(), new Set(), new Set(), new Set()]);
+      this._commandsClean.set(
+        command,
+        lexicalEditor.registerCommand(
+          command,
+          (payload: any) => {
+            for (let i = 4; i >= 0; i--) {
+              const listenerInPriorityOrder = this._commands.get(command);
+
+              if (listenerInPriorityOrder !== undefined) {
+                const listenersSet = listenerInPriorityOrder[i];
+                for (const listener of listenersSet) {
+                  if (listener(payload, lexicalEditor)) {
+                    return true;
+                  }
+                }
+              }
+            }
+            return false;
+          },
+          COMMAND_PRIORITY_CRITICAL,
+        ),
+      );
+    }
+
+    const listenersInPriorityOrder = commandsMap.get(command);
+
+    if (listenersInPriorityOrder === undefined) {
+      return () => {};
+    }
+
+    const listeners = listenersInPriorityOrder[priority];
+    listeners.add(listener as CommandListener<unknown>);
+    return () => {
+      listeners.delete(listener as CommandListener<unknown>);
+
+      if (listenersInPriorityOrder.every((listenersSet) => listenersSet.size === 0)) {
+        commandsMap.delete(command);
+        this._commandsClean.get(command)?.();
+      }
+    };
+  }
 }

src/editor-kernel/types.ts

@@ -1,4 +1,5 @@
 import type {
+  CommandListener,
   CommandPayloadType,
   DecoratorNode,
   LexicalCommand,
@@ -8,6 +9,17 @@ import type {
 
 import type DataSource from './data-source';
 
+export type CommandListenerPriority = 0 | 1 | 2 | 3 | 4;
+
+export const COMMAND_PRIORITY_EDITOR = 0;
+export const COMMAND_PRIORITY_LOW = 1;
+export const COMMAND_PRIORITY_NORMAL = 2;
+export const COMMAND_PRIORITY_HIGH = 3;
+export const COMMAND_PRIORITY_CRITICAL = 4;
+
+export type Commands = Map<LexicalCommand<unknown>, Array<Set<CommandListener<unknown>>>>;
+export type CommandsClean = Map<LexicalCommand<unknown>, () => void>;
+
 /**
  * Internationalization key type declaration, plugins can extend through declaration merging
  */
@@ -114,6 +126,35 @@ export interface IEditor {
    * @param listener
    */
   once<T extends keyof IKernelEventMap>(event: T, listener: IKernelEventMap[T]): this;
+
+  /**
+   * Extends the priority level of Lexical commands.
+   * Registers a listener that triggers when the provided command is dispatched
+   * via {@link LexicalEditor.dispatch}. The listener is triggered based on its priority.
+   * Listeners with higher priority can "intercept" commands and prevent them
+   * from propagating to other handlers by returning true.
+   *
+   * Listeners are always invoked within {@link LexicalEditor.update} and can call dollar functions.
+   *
+   * Listeners registered at the same priority level will deterministically run
+   * in the order of registration.
+   *
+   * @param command - The command that triggers the callback.
+   * @param listener - The function executed when the command is dispatched.
+   * @param priority - The relative priority of the listener. 0 | 1 | 2 | 3 | 4
+   *   (or {@link COMMAND_PRIORITY_EDITOR} |
+   *     {@link COMMAND_PRIORITY_LOW} |
+   *     {@link COMMAND_PRIORITY_NORMAL} |
+   *     {@link COMMAND_PRIORITY_HIGH} |
+   *     {@link COMMAND_PRIORITY_CRITICAL})
+   * @returns A teardown function to clean up the listener.
+   */
+  registerHighCommand<P>(
+    command: LexicalCommand<P>,
+    listener: CommandListener<P>,
+    priority: CommandListenerPriority,
+  ): () => void;
+
   /**
    * Register internationalization text
    * @param locale Internationalization text object
@@ -127,6 +168,7 @@ export interface IEditor {
    * Register multiple editor plugins
    */
   registerPlugins(plugins: Array<IPlugin>): IEditor;
+
   /**
    * Get editor Service, usually provided by plugins to extend certain functionalities
    * @param serviceId
@@ -177,6 +219,7 @@ export interface IEditorKernel extends IEditor {
    * @param dataSource
    */
   registerDataSource(dataSource: DataSource): void;
+
   /**
    * Register editor node decorator
    * @param name
@@ -186,6 +229,7 @@ export interface IEditorKernel extends IEditor {
     name: string,
     decorator: (_node: DecoratorNode<any>, _editor: LexicalEditor) => any,
   ): void;
+
   /**
    * Register Lexical Node
    * @param nodes
@@ -197,6 +241,7 @@ export interface IEditorKernel extends IEditor {
    * @param service
    */
   registerService<T>(serviceId: IServiceID<T>, service: T): void;
+
   /**
    * Register theme
    * @param themes

src/plugins/common/plugin/index.ts

@@ -249,7 +249,7 @@ export const CommonPlugin: IEditorPluginConstructor<CommonPluginOptions> = class
       registerDragonSupport(editor),
       registerHistory(editor, createEmptyHistoryState(), 300),
       registerHeaderBackspace(editor),
-      registerRichKeydown(editor),
+      registerRichKeydown(editor, this.kernel),
       registerCommands(editor),
     );
   }

src/plugins/common/plugin/register.ts

@@ -14,7 +14,6 @@ import {
   $isRootOrShadowRoot,
   $isTextNode,
   $setSelection,
-  COMMAND_PRIORITY_CRITICAL,
   COMMAND_PRIORITY_EDITOR,
   COMMAND_PRIORITY_NORMAL,
   ElementNode,
@@ -32,6 +31,7 @@ import {
 } from 'lexical';
 
 import { CONTROL_OR_META, CONTROL_OR_META_AND_SHIFT } from '@/common/sys';
+import { IEditor } from '@/types';
 
 function resolveElement(
   element: ElementNode,
@@ -160,9 +160,9 @@ export function registerHeaderBackspace(editor: LexicalEditor) {
   );
 }
 
-export function registerRichKeydown(editor: LexicalEditor) {
+export function registerRichKeydown(editor: LexicalEditor, kernel: IEditor) {
   return mergeRegister(
-    editor.registerCommand(
+    kernel.registerHighCommand(
       KEY_DOWN_COMMAND,
       (payload) => {
         // ctrl + shift + x
@@ -184,7 +184,7 @@ export function registerRichKeydown(editor: LexicalEditor) {
       },
       COMMAND_PRIORITY_EDITOR,
     ),
-    editor.registerCommand(
+    kernel.registerHighCommand(
       KEY_ARROW_UP_COMMAND,
       (event) => {
         const selection = $getSelection();
@@ -215,9 +215,9 @@ export function registerRichKeydown(editor: LexicalEditor) {
         }
         return false;
       },
-      COMMAND_PRIORITY_NORMAL,
+      COMMAND_PRIORITY_EDITOR,
     ),
-    editor.registerCommand<KeyboardEvent>(
+    kernel.registerHighCommand<KeyboardEvent>(
       KEY_ARROW_DOWN_COMMAND,
       (event) => {
         const selection = $getSelection();
@@ -263,9 +263,9 @@ export function registerRichKeydown(editor: LexicalEditor) {
         }
         return false;
       },
-      COMMAND_PRIORITY_CRITICAL,
+      COMMAND_PRIORITY_EDITOR,
     ),
-    editor.registerCommand(
+    kernel.registerHighCommand(
       KEY_ARROW_RIGHT_COMMAND,
       (event) => {
         const selection = $getSelection();
@@ -296,7 +296,7 @@ export function registerRichKeydown(editor: LexicalEditor) {
         }
         return false;
       },
-      COMMAND_PRIORITY_CRITICAL,
+      COMMAND_PRIORITY_EDITOR,
     ),
   );
 }