From fad90c6132c6c1fcbb55d31fa5bd3b54868086f8 Mon Sep 17 00:00:00 2001
From: Dominic Gannaway <trueadm@users.noreply.github.com>
Date: Fri, 10 Feb 2023 14:12:25 +0000
Subject: [PATCH] Add KEY_DOWN_COMMAND (#3878)

---
 packages/lexical-website/docs/faq.md    | 38 +++++++++++++++++++++++++
 packages/lexical/src/LexicalCommands.ts |  2 ++
 packages/lexical/src/LexicalEvents.ts   |  5 ++++
 packages/lexical/src/index.ts           |  1 +
 4 files changed, 46 insertions(+)

diff --git a/packages/lexical-website/docs/faq.md b/packages/lexical-website/docs/faq.md
index 8915c315538..941aa888433 100644
--- a/packages/lexical-website/docs/faq.md
+++ b/packages/lexical-website/docs/faq.md
@@ -61,3 +61,41 @@ editor.update(() => {
   $getRoot().clear();
 })
 ```
+
+## How do I listen to specific key down events?
+
+You can leverage Lexical's command listening system. Lexical provides specific commands for many common keyboard operations, such as:
+
+- `KEY_ARROW_LEFT_COMMAND`
+- `KEY_ARROW_RIGHT_COMMAND`
+- `KEY_ARROW_UP_COMMAND`
+- `KEY_ARROW_DOWN_COMMAND`
+- `KEY_SPACE_COMMAND`
+- `KEY_ENTER_COMMAND`
+- `KEY_BACKSPACE_COMMAND`
+- `KEY_DELETE_COMMAND`
+- `KEY_TAB_COMMAND`
+- `KEY_ESCAPE_COMMAND`
+
+```js
+import {KEY_ENTER_COMMAND, COMMAND_PRIORITY_LOW} from 'lexical';
+
+editor.addCommandListener(KEY_ENTER_COMMAND, (event: KeyboardEvent) => {
+  // Handle enter key presses here
+  return false;
+}, COMMAND_PRIORITY_LOW)
+```
+
+You can use the generic `KEY_DOWN_COMMAND` command to listen
+to all keydown events. Do note, that returning `true` in your listener will prevent any
+other key based commands from firing, so in most cases you'll want to return `false` from
+the command listener.
+
+```js
+import {KEY_DOWN_COMMAND, COMMAND_PRIORITY_LOW} from 'lexical';
+
+editor.addCommandListener(KEY_DOWN_COMMAND, (event: KeyboardEvent) => {
+  // Handle event here
+  return false;
+}, COMMAND_PRIORITY_LOW)
+```
\ No newline at end of file
diff --git a/packages/lexical/src/LexicalCommands.ts b/packages/lexical/src/LexicalCommands.ts
index 059155e6293..e80a5be7160 100644
--- a/packages/lexical/src/LexicalCommands.ts
+++ b/packages/lexical/src/LexicalCommands.ts
@@ -46,6 +46,8 @@ export const FORMAT_TEXT_COMMAND: LexicalCommand<TextFormatType> =
   createCommand('FORMAT_TEXT_COMMAND');
 export const UNDO_COMMAND: LexicalCommand<void> = createCommand('UNDO_COMMAND');
 export const REDO_COMMAND: LexicalCommand<void> = createCommand('REDO_COMMAND');
+export const KEY_DOWN_COMMAND: LexicalCommand<KeyboardEvent> =
+  createCommand('KEYDOWN_COMMAND');
 export const KEY_ARROW_RIGHT_COMMAND: LexicalCommand<KeyboardEvent> =
   createCommand('KEY_ARROW_RIGHT_COMMAND');
 export const MOVE_TO_END: LexicalCommand<KeyboardEvent> =
diff --git a/packages/lexical/src/LexicalEvents.ts b/packages/lexical/src/LexicalEvents.ts
index f2695d182cd..47c82491544 100644
--- a/packages/lexical/src/LexicalEvents.ts
+++ b/packages/lexical/src/LexicalEvents.ts
@@ -50,6 +50,7 @@ import {
   KEY_ARROW_UP_COMMAND,
   KEY_BACKSPACE_COMMAND,
   KEY_DELETE_COMMAND,
+  KEY_DOWN_COMMAND,
   KEY_ENTER_COMMAND,
   KEY_ESCAPE_COMMAND,
   KEY_SPACE_COMMAND,
@@ -862,6 +863,10 @@ function onKeyDown(event: KeyboardEvent, editor: LexicalEditor): void {
 
   const {keyCode, shiftKey, ctrlKey, metaKey, altKey} = event;
 
+  if (dispatchCommand(editor, KEY_DOWN_COMMAND, event)) {
+    return;
+  }
+
   if (isMoveForward(keyCode, ctrlKey, altKey, metaKey)) {
     dispatchCommand(editor, KEY_ARROW_RIGHT_COMMAND, event);
   } else if (isMoveToEnd(keyCode, ctrlKey, shiftKey, altKey, metaKey)) {
diff --git a/packages/lexical/src/index.ts b/packages/lexical/src/index.ts
index f8cd63e21a9..1da65bd6717 100644
--- a/packages/lexical/src/index.ts
+++ b/packages/lexical/src/index.ts
@@ -88,6 +88,7 @@ export {
   KEY_ARROW_UP_COMMAND,
   KEY_BACKSPACE_COMMAND,
   KEY_DELETE_COMMAND,
+  KEY_DOWN_COMMAND,
   KEY_ENTER_COMMAND,
   KEY_ESCAPE_COMMAND,
   KEY_MODIFIER_COMMAND,