Add support for keyboard shortcuts to <MenuItemLink>

Author: djhi

docs/Menu.md

@@ -183,16 +183,34 @@ export const MyMenu = () => (
 );
 ```
 
-| Prop          | Required | Type                 | Default | Description                              |
-| ------------- | -------- | -------------------- | ------- | ---------------------------------------- |
-| `to`          | Required | `string | location`  | -       | The menu item's target. It is passed to a React Router [NavLink](https://reacttraining.com/react-router/web/api/NavLink) component. |
-| `primaryText` | Required | `ReactNode`          | -       | The menu content, displayed when the menu isn't minimized. |
-| `leftIcon`    | Optional | `ReactNode`          | -       | The menu icon |
+| Prop               | Required | Type                 | Default | Description                              |
+| ------------------ | -------- | -------------------- | ------- | ---------------------------------------- |
+| `to`               | Required | `string | location`  | -       | The menu item's target. It is passed to a React Router [NavLink](https://reacttraining.com/react-router/web/api/NavLink) component. |
+| `primaryText`      | Required | `ReactNode`          | -       | The menu content, displayed when the menu isn't minimized. |
+| `keyboardShortcut` | Optional | `string | string[]`  | -       | The keyboard shortcut(s) to activate this menu item |
+| `leftIcon`         | Optional | `ReactNode`          | -       | The menu icon |
+| `sx`               | Optional | `SxProp`             | -       | Style overrides, powered by MUI System |
 
 Additional props are passed down to [the underling Material UI `<MenuItem>` component](https://mui.com/material-ui/api/menu-item/).
 
+### `to`
 
-The `primaryText` prop accepts a string, that react-admin passes through the [translation utility](./Translation.md). Alternately, you can set the menu item content using the `children`, e.g. to display a badge on top of the menu item:
+The menu item's target. It is passed to a React Router [NavLink](https://reacttraining.com/react-router/web/api/NavLink) component.
+
+```tsx
+// in src/MyMenu.js
+import { Menu } from 'react-admin';
+
+export const MyMenu = () => (
+    <Menu>
+        <Menu.Item to="/custom-route" primaryText="Miscellaneous" />
+    </Menu>
+);
+```
+
+### `primaryText`
+
+The menu content, displayed when the menu isn't minimized. It accepts a string, that react-admin passes through the [translation utility](./Translation.md). Alternately, you can set the menu item content using the `children`, e.g. to display a badge on top of the menu item:
 
 ```jsx
 import Badge from '@mui/material/Badge';
@@ -212,6 +230,24 @@ export const MyMenu = () => (
 
 Note that if you use the `children` prop, you'll have to translate the menu item content yourself using [`useTranslate`](./useTranslate.md). You'll also need to provide a `primaryText` either way, because it will be rendered in the tooltip when the side menu is collapsed.
 
+### `keyboardShortcut`
+
+The keyboard shortcut(s) to activate this menu item. Pass a string or an array of string that defines the supported keyboard shortcuts:
+
+```tsx
+export const MyMenu = () => (
+    <Menu>
+        <Menu.Item
+            to="/sales"
+            primaryText="Sales"
+            keyboardShortcut="ctrl+alt+S"
+        />
+    </Menu>
+);
+```
+
+### `leftIcon`
+
 The `letfIcon` prop allows setting the menu left icon.
 
 ```jsx
@@ -231,7 +267,16 @@ export const MyMenu = () => (
 );
 ```
 
-Additional props are passed down to [the underling Material UI `<MenuItem>` component](https://mui.com/material-ui/api/menu-item/).
+### `sx`
+
+You can use the `sx` prop to customize the style of the component.
+
+| Rule name                   | Description                                                         |
+|-----------------------------|---------------------------------------------------------------------|
+| `&.RaMenuItemLink-active`  | Applied to the underlying `MuiMenuItem`'s `activeClassName` prop    |
+| `& .RaMenuItemLink-icon`    | Applied to the `ListItemIcon` component when `leftIcon` prop is set |
+
+To override the style of all instances of `<MenuItemLink>` using the [application-wide style overrides](./AppTheme.md#theming-individual-components), use the `RaMenuItemLink` key.
 
 **Tip**: The `<Menu.Item>` component makes use of the React Router [NavLink](https://reactrouter.com/docs/en/v6/components/nav-link) component, hence allowing to customize the active menu style. For instance, here is how to use a custom theme to show a left border for the active menu:
 
@@ -260,15 +305,6 @@ export const theme = {
 };
 ```
 
-You can use the `sx` prop to customize the style of the component.
-
-| Rule name                   | Description                                                         |
-|-----------------------------|---------------------------------------------------------------------|
-| `&.RaMenuItemLink-active`  | Applied to the underlying `MuiMenuItem`'s `activeClassName` prop    |
-| `& .RaMenuItemLink-icon`    | Applied to the `ListItemIcon` component when `leftIcon` prop is set |
-
-To override the style of all instances of `<MenuItemLink>` using the [application-wide style overrides](./AppTheme.md#theming-individual-components), use the `RaMenuItemLink` key.
-
 ## `<Menu.DashboardItem>`
 
 The `<Menu.DashboardItem>` component displays a menu item for the dashboard.

jest.config.js

@@ -25,7 +25,7 @@ module.exports = {
         '/packages/create-react-admin/templates',
     ],
     transformIgnorePatterns: [
-        '[/\\\\]node_modules[/\\\\](?!(@hookform)/).+\\.(js|jsx|mjs|ts|tsx)$',
+        '[/\\\\]node_modules[/\\\\](?!(@hookform|react-hotkeys-hook)/).+\\.(js|jsx|mjs|ts|tsx)$',
     ],
     transform: {
         // '^.+\\.[tj]sx?$' to process js/ts with `ts-jest`

packages/ra-ui-materialui/package.json

@@ -79,6 +79,7 @@
         "query-string": "^7.1.3",
         "react-dropzone": "^14.2.3",
         "react-error-boundary": "^4.0.13",
+        "react-hotkeys-hook": "^5.1.0",
         "react-transition-group": "^4.4.5"
     },
     "gitHead": "587df4c27bfcec4a756df4f95e5fc14728dfc0d7"

packages/ra-ui-materialui/src/KeyboardShortcut.tsx

@@ -0,0 +1,19 @@
+import {
+    type HotkeyCallback,
+    type Keys,
+    type Options,
+    useHotkeys,
+} from 'react-hotkeys-hook';
+
+export const KeyboardShortcut = (props: KeyboardShortcutProps) => {
+    const { callback, dependencies, keys, options } = props;
+    useHotkeys(keys, callback, options, dependencies);
+    return null;
+};
+
+export interface KeyboardShortcutProps {
+    keys: Keys;
+    callback: HotkeyCallback;
+    options?: Options;
+    dependencies?: readonly unknown[];
+}

packages/ra-ui-materialui/src/getKeyboardShortcutLabel.ts

@@ -0,0 +1,10 @@
+import { Keys } from 'react-hotkeys-hook';
+
+export const getKeyboardShortcutLabel = (keyboardShortcut: Keys) => {
+    if (typeof keyboardShortcut === 'string') {
+        return keyboardShortcut.split('+').join(' + ');
+    }
+    return keyboardShortcut
+        .map(shortcut => getKeyboardShortcutLabel(shortcut))
+        .join(', ');
+};

packages/ra-ui-materialui/src/index.ts

@@ -12,3 +12,5 @@ export * from './list';
 export * from './preferences';
 export * from './AdminUI';
 export * from './AdminContext';
+export * from './KeyboardShortcut';
+export * from './getKeyboardShortcutLabel';

packages/ra-ui-materialui/src/layout/DashboardMenuItem.tsx

@@ -1,6 +1,5 @@
 import React from 'react';
 import DashboardIcon from '@mui/icons-material/Dashboard';
-import { To } from 'react-router';
 import { useBasename } from 'ra-core';
 
 import { MenuItemLink, MenuItemLinkProps } from './MenuItemLink';
@@ -24,8 +23,9 @@ export const DashboardMenuItem = (props: DashboardMenuItemProps) => {
     );
 };
 
-export interface DashboardMenuItemProps extends Omit<MenuItemLinkProps, 'to'> {
-    to?: To;
+export interface DashboardMenuItemProps
+    extends Omit<MenuItemLinkProps, 'to'>,
+        Partial<Pick<MenuItemLinkProps, 'to'>> {
     /**
      * @deprecated
      */

packages/ra-ui-materialui/src/layout/Menu.spec.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { Default, WithDashboard, WithKeyboardShortcuts } from './Menu.stories';
+
+describe('<Menu>', () => {
+    it('should render a default menu with items for all registered resources', async () => {
+        render(<Default />);
+        await screen.findByText('Posts', { selector: '[role="menuitem"]' });
+        await screen.findByText('Comments', { selector: '[role="menuitem"]' });
+        await screen.findByText('Tags', { selector: '[role="menuitem"]' });
+        await screen.findByText('Users', { selector: '[role="menuitem"]' });
+        await screen.findByText('Orders', { selector: '[role="menuitem"]' });
+        await screen.findByText('Reviews', { selector: '[role="menuitem"]' });
+    });
+
+    it('should render a default menu with items for all registered resources and the dashboard', async () => {
+        render(<WithDashboard />);
+        await screen.findByText('Dashboard', { selector: '[role="menuitem"]' });
+        await screen.findByText('Posts', { selector: '[role="menuitem"]' });
+        await screen.findByText('Comments', { selector: '[role="menuitem"]' });
+        await screen.findByText('Tags', { selector: '[role="menuitem"]' });
+        await screen.findByText('Users', { selector: '[role="menuitem"]' });
+        await screen.findByText('Orders', { selector: '[role="menuitem"]' });
+        await screen.findByText('Reviews', { selector: '[role="menuitem"]' });
+    });
+
+    it('should support keyboard shortcuts', async () => {
+        render(<WithKeyboardShortcuts />);
+        await screen.findByText('Dashboard', { selector: '[role="menuitem"]' });
+        fireEvent.keyDown(global.document, {
+            key: 'c',
+            code: 'KeyC',
+            ctrlKey: true,
+            altKey: true,
+        });
+        expect(await screen.findAllByText('Customers')).toHaveLength(2);
+        fireEvent.keyDown(global.document, {
+            key: 's',
+            code: 'KeyS',
+            ctrlKey: true,
+            altKey: true,
+        });
+        expect(await screen.findAllByText('Sales')).toHaveLength(2);
+        fireEvent.keyDown(global.document, {
+            key: 'p',
+            code: 'KeyP',
+            ctrlKey: true,
+            altKey: true,
+        });
+        expect(await screen.findAllByText('Products')).toHaveLength(2);
+        fireEvent.keyDown(global.document, {
+            key: 'd',
+            code: 'KeyD',
+            ctrlKey: true,
+            altKey: true,
+        });
+        expect(await screen.findAllByText('Dashboard')).toHaveLength(2);
+    });
+});

packages/ra-ui-materialui/src/layout/Menu.stories.tsx

@@ -63,6 +63,31 @@ export const Default = () => {
     );
 };
 
+export const WithDashboard = () => {
+    const MenuDefault = () => <Menu hasDashboard={true} dense={false} />;
+    const DefaultLayout = ({ children }) => (
+        <Layout menu={MenuDefault}>{children}</Layout>
+    );
+    const Dashboard = () => <Page title="Dashboard" />;
+
+    return (
+        <Admin
+            store={memoryStore()}
+            dataProvider={testDataProvider()}
+            layout={DefaultLayout}
+            dashboard={Dashboard}
+        >
+            {resources.map((resource, index) => (
+                <Resource
+                    name={resource}
+                    key={`resource_${index}`}
+                    list={<DemoList name={resource} />}
+                />
+            ))}
+        </Admin>
+    );
+};
+
 export const Dense = () => {
     const MenuDense = () => <Menu hasDashboard={true} dense={true} />;
     const LayoutDense = ({ children }) => (
@@ -135,6 +160,54 @@ export const Custom = () => {
     );
 };
 
+export const WithKeyboardShortcuts = () => {
+    const CustomMenu = () => (
+        <Menu>
+            <Menu.DashboardItem keyboardShortcut="ctrl+alt+D" />
+            <Menu.Item
+                to="/sales"
+                leftIcon={<PieChartOutlined />}
+                primaryText="Sales"
+                keyboardShortcut="ctrl+alt+S"
+            />
+            <Menu.Item
+                to="/customers"
+                leftIcon={<PeopleOutlined />}
+                primaryText="Customers"
+                keyboardShortcut="ctrl+alt+C"
+            />
+            <Menu.ResourceItem
+                name="products"
+                leftIcon={<Inventory />}
+                keyboardShortcut="ctrl+alt+P"
+            />
+        </Menu>
+    );
+    const CustomLayout = ({ children }) => (
+        <Layout menu={CustomMenu}>{children}</Layout>
+    );
+
+    const Dashboard = () => <Page title="Dashboard" />;
+    return (
+        <TestMemoryRouter initialEntries={['/']}>
+            <Admin
+                dataProvider={testDataProvider()}
+                layout={CustomLayout}
+                dashboard={Dashboard}
+            >
+                <Resource name="products" list={<Page title="Products" />} />
+                <CustomRoutes>
+                    <Route path="/sales" element={<Page title="Sales" />} />
+                    <Route
+                        path="/customers"
+                        element={<Page title="Customers" />}
+                    />
+                </CustomRoutes>
+            </Admin>
+        </TestMemoryRouter>
+    );
+};
+
 const Page = ({ title }) => (
     <>
         <Typography variant="h5" mt={2}>

packages/ra-ui-materialui/src/layout/Menu.tsx

@@ -44,7 +44,12 @@ export const Menu = (inProps: MenuProps) => {
         props: inProps,
         name: PREFIX,
     });
-    const { children, className, ...rest } = props;
+    const {
+        children,
+        className,
+        hasDashboard: hasDashboardProp,
+        ...rest
+    } = props;
     const hasDashboard = useHasDashboard();
     const [open] = useSidebarState();