feat(react-keytips): add invokeEvent prop (#251)

Co-authored-by: Martin Hochel <[email protected]>

Author: mainframev

change/@fluentui-contrib-react-keytips-6c388a16-92f8-4352-a0e6-37f7bdd0eb14.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: add invokeEvent prop",
+  "packageName": "@fluentui-contrib/react-keytips",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-keytips/src/components/Keytips/Keytips.component-browser-spec.tsx

@@ -128,3 +128,26 @@ test.describe('keytip and dynamic content update', () => {
     ).toBeVisible();
   });
 });
+
+test.describe('keytips should have invoking events', () => {
+  test('it should invoke on keyup event', async ({ mount, page }) => {
+    await mount(<KeytipsBasicExample invokeEvent="keyup" />);
+    const tooltip = page.getByRole('tooltip');
+    await page.keyboard.down('Alt');
+    await page.keyboard.down('Meta');
+    await expect(tooltip).toBeHidden();
+    await page.keyboard.press('Alt+Meta');
+    await expect(tooltip).toBeVisible();
+  });
+
+  test('it should invoke on keydown event', async ({ mount, page }) => {
+    await mount(<KeytipsBasicExample />);
+    const tooltip = page.getByRole('tooltip');
+    await page.keyboard.up('Alt');
+    await page.keyboard.up('Meta');
+    await expect(tooltip).toBeHidden();
+    await page.keyboard.down('Alt');
+    await page.keyboard.down('Meta');
+    await expect(tooltip).toBeVisible();
+  });
+});

packages/react-keytips/src/components/Keytips/Keytips.test.tsx

@@ -116,4 +116,40 @@ describe('Keytips', () => {
     expect(screen.queryAllByRole('tooltip')).toHaveLength(0);
     expect(onExitKeytipsMode).toHaveBeenCalledTimes(1);
   });
+
+  it('should support different invoking event', async () => {
+    const addEventListener = jest.spyOn(document, 'addEventListener');
+    const removeEventListener = jest.spyOn(document, 'removeEventListener');
+
+    const Component = () => {
+      const ref = useKeytipRef({
+        keySequences: ['a'],
+        content: 'A',
+      });
+
+      return (
+        <>
+          {/* default is keydown */}
+          <Keytips invokeEvent="keyup" />
+          <Button ref={ref}>keytip A</Button>
+        </>
+      );
+    };
+
+    const { unmount } = render(<Component />);
+
+    await act(async () => await userEvent.keyboard('{Alt>}{Meta}'));
+
+    expect(addEventListener).toHaveBeenCalledWith(
+      'keyup',
+      expect.any(Function)
+    );
+
+    unmount();
+
+    expect(removeEventListener).toHaveBeenCalledWith(
+      'keyup',
+      expect.any(Function)
+    );
+  });
 });

packages/react-keytips/src/components/Keytips/Keytips.types.ts

@@ -25,27 +25,32 @@ export type KeytipsProps = ComponentProps<KeytipsSlots> &
     content?: string;
     /**
      * Key sequence that will start keytips mode
-     * @default 'alt+meta'
+     * @default 'alt+meta'.
      */
     startSequence?: string;
     /**
      * Key sequences that execute the return functionality in keytips
-     * (going back to the previous level of keytips)
+     * (going back to the previous level of keytips).
      * @default 'escape'
      */
     returnSequence?: string;
     /**
-     * Key sequences that will exit keytips mode
+     * Key sequences that will exit keytips mode.
      */
     exitSequence?: string;
     /**
      * Callback function triggered when keytip mode is exited.
      */
     onExitKeytipsMode?: EventHandler<OnExitKeytipsModeData>;
     /**
-     * Callback function triggered when keytip mode is entered
+     * Callback function triggered when keytip mode is entered.
      */
     onEnterKeytipsMode?: EventHandler<OnEnterKeytipsModeData>;
+    /**
+     * Event responsible for invoking keytips.
+     * @default 'keydown'
+     * */
+    invokeEvent?: 'keydown' | 'keyup';
   };
 
 /**

packages/react-keytips/src/components/Keytips/useKeytips.tsx

@@ -29,6 +29,7 @@ export const useKeytips_unstable = (props: KeytipsProps): KeytipsState => {
     returnSequence = 'escape',
     onEnterKeytipsMode,
     onExitKeytipsMode,
+    invokeEvent = 'keydown',
   } = props;
   const { subscribe, reset } = useEventService();
   const [state, dispatch] = useKeytipsState();
@@ -92,13 +93,16 @@ export const useKeytips_unstable = (props: KeytipsProps): KeytipsState => {
     [state.inKeytipMode]
   );
 
-  useHotkeys([
-    [startSequence, handleEnterKeytipMode],
-    [returnSequence, handleReturnSequence],
-    ...[exitSequence, 'tab', 'enter', 'space'].map(
-      (key) => [key, handleExitKeytipMode] as Hotkey
-    ),
-  ]);
+  useHotkeys(
+    [
+      [startSequence, handleEnterKeytipMode],
+      [returnSequence, handleReturnSequence],
+      ...[exitSequence, 'tab', 'enter', 'space'].map(
+        (key) => [key, handleExitKeytipMode] as Hotkey
+      ),
+    ],
+    invokeEvent
+  );
 
   React.useEffect(() => {
     const handleKeytipAdded = (keytip: KeytipWithId) => {
@@ -197,7 +201,7 @@ export const useKeytips_unstable = (props: KeytipsProps): KeytipsState => {
   React.useEffect(() => {
     if (!targetDocument) return;
 
-    const handleKeyDown = (ev: KeyboardEvent) => {
+    const handleInvokeEvent = (ev: KeyboardEvent) => {
       ev.preventDefault();
       ev.stopPropagation();
 
@@ -215,9 +219,9 @@ export const useKeytips_unstable = (props: KeytipsProps): KeytipsState => {
       handlePartiallyMatchedNodes(currSeq);
     };
 
-    targetDocument?.addEventListener('keydown', handleKeyDown);
+    targetDocument?.addEventListener(invokeEvent, handleInvokeEvent);
     return () => {
-      targetDocument?.removeEventListener('keydown', handleKeyDown);
+      targetDocument?.removeEventListener(invokeEvent, handleInvokeEvent);
     };
   }, [
     state.inKeytipMode,

packages/react-keytips/src/docs/MIGRATION.md

@@ -11,7 +11,7 @@ This Migration guide is a work in progress and is not yet ready for use.
   - `keytipExitSequence` -> renamed to `exitSequence`, instead of `IKeytipTransitionKey[]`
     accepts a string value. Can be a single key or a combination of keys separated by "+".
   - `keytipStartSequence` -> renamed to `startSequence`, instead of `IKeytipTransitionKey[]`,
-    accepts a string value (default: "alt+control"). Can be a single key or a combination of keys separated by "+".
+    accepts a string value (default: "alt+meta (alt+win on Windows)"). Can be a single key or a combination of keys separated by "+".
   - `keytipReturnSequence` -> renamed to `returnSequence`, instead of `IKeytipTransitionKey[]`,
     accepts a string value. Can be a single key or a combination of keys separated by "+".
   - `styles` - Not supported.
@@ -22,6 +22,6 @@ This Migration guide is a work in progress and is not yet ready for use.
   - `styles` - Not supported.
   - `theme` - Not supported.
   - `disabled` - Not supported. `Keytip` won't appear for disabled target.
-    `callOutProps` -> Not supported. Instead there are multiple props available, that has to be used individually: `positioning`, `appearance`, `visible`, `content`.
+    `callOutProps` -> Not supported. Instead there are multiple props available, that has to be used individually: `positioning`, `visible`, `content`.
   - `hasDynamicChildren` and `hasMenu` - merged into `dynamic` prop. If `Keytip` triggers dynamic content: Menu, Modal, Tabs or any other item that
     that has keytips, set `dynamic` to `true`.

packages/react-keytips/src/hooks/useHotkeys.ts

@@ -2,6 +2,7 @@ import {
   useIsomorphicLayoutEffect,
   useFluent,
 } from '@fluentui/react-components';
+import { KeytipsProps } from '../components/Keytips/Keytips.types';
 
 type Options = { preventDefault?: boolean; stopPropagation?: boolean };
 export type Hotkey = [string, (ev: KeyboardEvent) => void, Options?];
@@ -54,7 +55,11 @@ const isKeyMatchingKeyboardEvent = (
   return false;
 };
 
-export const useHotkeys = (hotkeys: Hotkey[], target?: Document) => {
+export const useHotkeys = (
+  hotkeys: Hotkey[],
+  invokeEvent: KeytipsProps['invokeEvent'] = 'keydown',
+  target?: Document
+) => {
   const { targetDocument } = useFluent();
   const doc = target ?? targetDocument;
 
@@ -85,9 +90,9 @@ export const useHotkeys = (hotkeys: Hotkey[], target?: Document) => {
       );
     };
 
-    doc?.addEventListener('keydown', listener);
+    doc?.addEventListener(invokeEvent, listener);
     return () => {
-      doc?.removeEventListener('keydown', listener);
+      doc?.removeEventListener(invokeEvent, listener);
     };
   }, [hotkeys, doc]);
 };