feat(react-keytips): add useKeytipsManager hook (microsoft#406)

Author: mainframev

change/@fluentui-contrib-react-keytips-b545453d-9b1f-4e07-ba20-8242826f07ec.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "BREAKING: add useKeytipsManager hook. useEventServices is no longer exported",
+  "packageName": "@fluentui-contrib/react-keytips",
+  "email": "vgenaev@gmail.com",
+  "dependentChangeType": "patch"
+}

packages/react-keytips/README.md

@@ -64,4 +64,29 @@ export const App = () => {
 };
 ```
 
+## Manual dispatching of keytip events
+
+In some cases, you may want to manually trigger keytip events. For example, you might need to programmatically enter or exit keytip mode based on action.
+The [useKeytipsManager](https://github.com/microsoft/fluentui-contrib/blob/main/packages/react-keytips/src/hooks/useKeytipsManager.ts) hook provides access to dispatch
+method, allowing you to send keytip events manually.
+
+```tsx
+import * as React from 'react';
+import { Button } from '@fluentui/react-components';
+import { useKeytipsManager } from '@fluentui-contrib/react-keytips';
+
+export const App = () => {
+  const { enterKeytipMode } = useKeytipsManager();
+
+  return (
+    <>
+      <Button onClick={enterKeytipMode}>Show Keytips</Button>
+    </>
+  );
+};
+```
+
+```tsx
+
 Follow up on the [Storybook](https://microsoft.github.io/fluentui-contrib/react-keytips) for examples on how to use the components provided by this package.
+```

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

@@ -30,6 +30,10 @@ export type ReturnKeytipEventHandler<E = HTMLElement | null> = EventHandler<
 >;
 
 export type KeytipProps = ComponentProps<KeytipSlots> & {
+  /**
+   * Unique identifier for the Keytip.
+   */
+  uniqueId?: string;
   /**
    * Positioning props to be passed to Keytip.
    * @default { align: 'center', position: 'below' }
@@ -68,11 +72,6 @@ export type KeytipProps = ComponentProps<KeytipSlots> & {
   overflowSequence?: string[];
 };
 
-/** @internal */
-export type KeytipWithId = KeytipProps & {
-  uniqueId: string;
-};
-
 export type KeytipState = ComponentState<KeytipSlots> &
   Required<Pick<KeytipProps, 'visible' | 'positioning' | 'content'>> & {
     /**

packages/react-keytips/src/components/Keytip/internal/Keytip.types.ts

@@ -0,0 +1,6 @@
+import type { KeytipProps } from '../Keytip.types';
+
+/** @internal */
+export type KeytipWithId = KeytipProps & {
+  uniqueId: string;
+};

packages/react-keytips/src/components/Keytip/useKeytip.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import type { KeytipProps, KeytipState } from './Keytip.types';
 import { usePositioning } from '@fluentui/react-positioning';
 import { useControllableState } from '@fluentui/react-utilities';
-import { KEYTIP_BORDER_RADIUS, KTP_ROOT_ID } from '../../constants';
+import { KEYTIP_BORDER_RADIUS } from '../../constants';
 import {
   useFluent,
   slot,

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

@@ -7,6 +7,7 @@ import {
   KeytipsDynamicExample,
   KeytipsDisabledTargetExample,
   KeytipsDisabledMenuTargetExample,
+  KeytipsManualDispatchedEvents,
 } from './KeytipsExamples.component-browser-spec';
 
 test.use({ viewport: { width: 500, height: 500 } });
@@ -24,6 +25,25 @@ test.describe('enter and exit from keytip mode interactions', () => {
     await expect(tooltip).toBeHidden();
   });
 
+  test('should enter and exit keytips mode by manually dispatching events', async ({
+    mount,
+    page,
+  }) => {
+    await mount(<KeytipsManualDispatchedEvents startSequence="alt+meta" />);
+
+    const tooltip = page.getByRole('tooltip');
+    await expect(tooltip).toBeHidden();
+
+    const enterButton = page.getByRole('button', { name: 'Enter keytip mode' });
+    const exitButton = page.getByRole('button', { name: 'Exit keytip mode' });
+    await enterButton.click();
+
+    await expect(tooltip).toBeVisible();
+
+    await exitButton.click();
+    await expect(tooltip).toBeHidden();
+  });
+
   test('should not show keytip for disabled target', async ({
     mount,
     page,

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

@@ -34,6 +34,7 @@ import {
 import { MoreHorizontal20Filled } from '@fluentui/react-icons';
 import { Keytips } from './Keytips';
 import type { KeytipsProps } from './Keytips.types';
+import { useKeytipsManager } from '../../hooks/useKeytipsManager';
 
 const useStyles = makeStyles({
   container: {
@@ -480,3 +481,27 @@ export const KeytipsDynamicExample = (props: KeytipsProps) => {
     </>
   );
 };
+
+export const KeytipsManualDispatchedEvents = (props: KeytipsProps) => {
+  const classes = useStyles();
+  const { enterKeytipMode, exitKeytipMode } = useKeytipsManager();
+
+  const normalButton = useKeytipRef({
+    keySequences: ['1c'],
+    content: '1C',
+    onExecute,
+  });
+
+  return (
+    <>
+      <Keytips {...props} />
+      <Button onClick={enterKeytipMode}>Enter keytip mode</Button>
+      <Button onClick={exitKeytipMode}>Exit keytip mode</Button>
+      <div className={classes.column}>
+        <div className={classes.row}>
+          <Button ref={normalButton}>Button</Button>
+        </div>
+      </div>
+    </>
+  );
+};