feat: Bind keyboard events to the current excalidraw container and add handleKeyboardGlobally prop to allow host to bind to document (#3430)

* fix: Bind keyboard events to excalidraw container

* fix cases around blurring

* fix modal rendering so keyboard shortcuts work on modal as well

* Revert "fix modal rendering so keyboard shortcuts work on modal as well"

This reverts commit 2c8ec6be8e.

* Attach keyboard event in react way so we need not handle portals separately (modals)

* dnt propagate esc event when modal shown

* focus the container when help dialog closed with shift+?

* focus the help icon when help dialog on close triggered

* move focusNearestTabbableParent to util

* rename util to focusNearestParent and remove outline from excal and modal

* Add prop bindKeyGlobally to decide if keyboard events should be binded to document and allow it in excal app, revert tests

* fix

* focus container after installing library, reset library and closing error dialog

* fix tests and create util to focus container

* Add excalidraw-container class to focus on the container

* pass focus container to library to focus current instance of excal

* update docs

* remove util as it wont be used anywhere

* fix propagation not being stopped for React keyboard handling

* tweak reamde

Co-authored-by: David Luzar <luzar.david@gmail.com>

* tweak changelog

* rename prop to handleKeyboardGlobally

Co-authored-by: dwelle <luzar.david@gmail.com>

src/actions/actionFinalize.tsx

@@ -18,7 +18,7 @@ import { isBindingElement } from "../element/typeChecks";
 
 export const actionFinalize = register({
   name: "finalize",
-  perform: (elements, appState, _, { canvas }) => {
+  perform: (elements, appState, _, { canvas, focusContainer }) => {
     if (appState.editingLinearElement) {
       const {
         elementId,
@@ -51,7 +51,7 @@ export const actionFinalize = register({
 
     let newElements = elements;
     if (window.document.activeElement instanceof HTMLElement) {
-      window.document.activeElement.blur();
+      focusContainer();
     }
 
     const multiPointElement = appState.multiElement

src/actions/actionMenu.tsx

@@ -70,7 +70,10 @@ export const actionFullScreen = register({
 
 export const actionShortcuts = register({
   name: "toggleShortcuts",
-  perform: (_elements, appState) => {
+  perform: (_elements, appState, _, { focusContainer }) => {
+    if (appState.showHelpDialog) {
+      focusContainer();
+    }
     return {
       appState: {
         ...appState,

src/actions/manager.tsx

@@ -12,7 +12,11 @@ import { MODES } from "../constants";
 
 // This is the <App> component, but for now we don't care about anything but its
 // `canvas` state.
-type App = { canvas: HTMLCanvasElement | null; props: AppProps };
+type App = {
+  canvas: HTMLCanvasElement | null;
+  focusContainer: () => void;
+  props: AppProps;
+};
 
 export class ActionManager implements ActionsManagerInterface {
   actions = {} as ActionsManagerInterface["actions"];
@@ -51,7 +55,7 @@ export class ActionManager implements ActionsManagerInterface {
     actions.forEach((action) => this.registerAction(action));
   }
 
-  handleKeyDown(event: KeyboardEvent) {
+  handleKeyDown(event: React.KeyboardEvent | KeyboardEvent) {
     const canvasActions = this.app.props.UIOptions.canvasActions;
     const data = Object.values(this.actions)
       .sort((a, b) => (b.keyPriority || 0) - (a.keyPriority || 0))

src/actions/types.ts

@@ -15,11 +15,13 @@ export type ActionResult =
     }
   | false;
 
+type AppAPI = { canvas: HTMLCanvasElement | null; focusContainer(): void };
+
 type ActionFn = (
   elements: readonly ExcalidrawElement[],
   appState: Readonly<AppState>,
   formData: any,
-  app: { canvas: HTMLCanvasElement | null },
+  app: AppAPI,
 ) => ActionResult | Promise<ActionResult>;
 
 export type UpdaterFn = (res: ActionResult) => void;
@@ -105,7 +107,7 @@ export interface Action {
   perform: ActionFn;
   keyPriority?: number;
   keyTest?: (
-    event: KeyboardEvent,
+    event: React.KeyboardEvent | KeyboardEvent,
     appState: AppState,
     elements: readonly ExcalidrawElement[],
   ) => boolean;
@@ -120,6 +122,6 @@ export interface Action {
 export interface ActionsManagerInterface {
   actions: Record<ActionName, Action>;
   registerAction: (action: Action) => void;
-  handleKeyDown: (event: KeyboardEvent) => boolean;
+  handleKeyDown: (event: React.KeyboardEvent | KeyboardEvent) => boolean;
   renderAction: (name: ActionName) => React.ReactElement | null;
 }