lobe-editor / rules

---
description: Comprehensive hotkey architecture and management standards for LobeHub Editor
---

# Hotkey Management Standards

## Building Blocks

| What                 | Where                                                                        |
| -------------------- | ---------------------------------------------------------------------------- |
| Hotkey ids           | `HotkeyEnum` in [src/types/hotkey.ts](mdc:src/types/hotkey.ts)               |
| Scopes and key names | `HotkeyScopeEnum`, `KeyEnum` in the same file                                |
| Default bindings     | `HOTKEYS_REGISTRATION` in [src/const/hotkey.ts](mdc:src/const/hotkey.ts)     |
| Options + matching   | [src/utils/hotkey/registerHotkey.ts](mdc:src/utils/hotkey/registerHotkey.ts) |
| Kernel API           | `kernel.registerHotkey(id, callback, options)` (returns a cleanup)           |

Current ids: `Bold`, `BulletList`, `CodeInline`, `Italic`, `Link`, `Mention`, `NumberList`,
`PasteAsPlainText`, `Redo`, `Slash`, `Strikethrough`, `Underline`, `Undo`.

```typescript
export type HotkeyOptions = {
  enabled?: boolean; // false: nothing is registered
  preventDefault?: boolean;
  stopImmediatePropagation?: boolean; // declared, currently not applied by registerHotkey
  stopPropagation?: boolean;
};
```

`kernel.registerHotkey` looks the id up in `HOTKEYS_REGISTRATION` (unknown ids are ignored),
returns a no-op when `enabled === false`, and otherwise registers a `KEY_DOWN_COMMAND`
listener at the binding's `priority`.

## Adding a Hotkey

1. Add the id to `HotkeyEnum` in `src/types/hotkey.ts`.
2. Add a `HotkeyItem` to `HOTKEYS_REGISTRATION` in `src/const/hotkey.ts`:

```typescript
{
  id: HotkeyEnum.Bold,
  keys: combineKeys([KeyEnum.Mod, 'b']),
  priority: COMMAND_PRIORITY_LOW,
  scopes: [HotkeyScopeEnum.Format],
},
```

3. Register it from the plugin's registry (next section) behind `enableHotkey`.

## Registering in a Plugin

Hotkeys are registered in the kernel layer, in `plugin/registry.ts` (`code`, `link`,
`link-highlight`, `list`) or `plugin/register.ts` (`common`):

```typescript
import { mergeRegister } from '@lexical/utils';
import { INSERT_UNORDERED_LIST_COMMAND } from '@lexical/list';
import type { LexicalEditor } from 'lexical';

import type { IEditorKernel } from '@/types';
import { HotkeyEnum } from '@/types/hotkey';

export interface ListRegistryOptions {
  enableHotkey?: boolean;
}

export function registerListCommands(
  editor: LexicalEditor,
  kernel: IEditorKernel,
  options?: ListRegistryOptions,
) {
  const { enableHotkey = true } = options || {};

  return mergeRegister(
    kernel.registerHotkey(
      HotkeyEnum.BulletList,
      () => editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND, undefined),
      { enabled: enableHotkey, preventDefault: true, stopImmediatePropagation: true },
    ),
    // ...commands and listeners
  );
}
```

Plugin class (`config` is `public` so `onInit` can read it):

```typescript
onInit(editor: LexicalEditor): void {
  this.register(
    registerListCommands(editor, this.kernel, { enableHotkey: this.config?.enableHotkey }),
  );
}
```

React plugin: expose `enableHotkey?: boolean` (default `true`) in `react/type.ts` and pass it
to `editor.registerPlugin(XPlugin, { enableHotkey, ... })`. Plugins with `enableHotkey` today:
`code`, `common`, `link`, `link-highlight`, `list`.

## Configuring Hotkeys as a User

Options are passed per plugin with `Editor.withProps`:

```tsx
import { ReactLinkPlugin, ReactListPlugin } from '@lobehub/editor';
import { Editor } from '@lobehub/editor/react';

<Editor
  plugins={[
    Editor.withProps(ReactLinkPlugin, { enableHotkey: false }),
    Editor.withProps(ReactListPlugin, { enableHotkey: false }),
  ]}
/>;
```

`getHotkeyById(id)` (exported from `@lobehub/editor`) returns a binding, e.g. to show the
shortcut in a toolbar tooltip.

## Rules

1. Default `enableHotkey` to `true` and use that exact prop name.
2. Never register hotkeys from React components; use the kernel registry.
3. New ids need both the `HotkeyEnum` entry and the `HOTKEYS_REGISTRATION` entry.
4. Test enabling and disabling the hotkey.