fix(react-tabster): improve support for concurrent mode (#34113)

Author: layershifter

change/@fluentui-react-tabster-536547dc-6700-44b1-b2c9-ee40eed86a6e.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: improve support for concurrent mode",
+  "packageName": "@fluentui/react-tabster",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-tabster/src/hooks/useActivateModal.ts

@@ -7,21 +7,20 @@ import { useTabster } from './useTabster';
  * Returns a function that activates a modal by element from the modal or modal container.
  */
 export function useActivateModal(): (elementFromModal: HTMLElement | undefined) => void {
-  const tabster = useTabster();
-  const modalizerAPI = tabster ? getModalizer(tabster) : undefined;
-  const [setActivateModalTimeout] = useTimeout();
+  const modalizerRefAPI = useTabster(getModalizer);
 
+  const [setActivateModalTimeout] = useTimeout();
   const activateModal = React.useCallback(
     (elementFromModal: HTMLElement | undefined) => {
       // We call the actual activation function on the next tick, because with the typical use case,
       // the hook will be called on the same tick when other Tabster attributes are being applied,
       // and on the current tick the element has just received the attributes, but Tabster has not
       // instantiated the Modalizer yet.
       setActivateModalTimeout(() => {
-        modalizerAPI?.activate(elementFromModal);
+        modalizerRefAPI.current?.activate(elementFromModal);
       }, 0);
     },
-    [modalizerAPI, setActivateModalTimeout],
+    [modalizerRefAPI, setActivateModalTimeout],
   );
 
   return activateModal;

packages/react-components/react-tabster/src/hooks/useArrowNavigationGroup.ts

@@ -49,11 +49,8 @@ export const useArrowNavigationGroup = (options: UseArrowNavigationGroupOptions
     // eslint-disable-next-line @typescript-eslint/naming-convention
     unstable_hasDefault,
   } = options;
-  const tabster = useTabster();
 
-  if (tabster) {
-    getMover(tabster);
-  }
+  useTabster(getMover);
 
   return useTabsterAttributes({
     mover: {

packages/react-components/react-tabster/src/hooks/useFocusFinders.ts

@@ -7,50 +7,50 @@ import { useTabster } from './useTabster';
  * Returns a set of helper functions that will traverse focusable elements in the context of a root DOM element
  */
 export const useFocusFinders = () => {
-  const tabster = useTabster();
+  const tabsterRef = useTabster();
   const { targetDocument } = useFluent();
 
   // Narrow props for now and let need dictate additional props in the future
   const findAllFocusable = React.useCallback(
     (container: HTMLElement, acceptCondition?: (el: HTMLElement) => boolean) =>
-      tabster?.focusable.findAll({ container, acceptCondition }) || [],
-    [tabster],
+      tabsterRef.current?.focusable.findAll({ container, acceptCondition }) || [],
+    [tabsterRef],
   );
 
   const findFirstFocusable = React.useCallback(
-    (container: HTMLElement) => tabster?.focusable.findFirst({ container }),
-    [tabster],
+    (container: HTMLElement) => tabsterRef.current?.focusable.findFirst({ container }),
+    [tabsterRef],
   );
 
   const findLastFocusable = React.useCallback(
-    (container: HTMLElement) => tabster?.focusable.findLast({ container }),
-    [tabster],
+    (container: HTMLElement) => tabsterRef.current?.focusable.findLast({ container }),
+    [tabsterRef],
   );
 
   const findNextFocusable = React.useCallback(
     (currentElement: HTMLElement, options: Pick<Partial<TabsterTypes.FindNextProps>, 'container'> = {}) => {
-      if (!tabster || !targetDocument) {
+      if (!tabsterRef.current || !targetDocument) {
         return null;
       }
 
       const { container = targetDocument.body } = options;
 
-      return tabster.focusable.findNext({ currentElement, container });
+      return tabsterRef.current.focusable.findNext({ currentElement, container });
     },
-    [tabster, targetDocument],
+    [tabsterRef, targetDocument],
   );
 
   const findPrevFocusable = React.useCallback(
     (currentElement: HTMLElement, options: Pick<Partial<TabsterTypes.FindNextProps>, 'container'> = {}) => {
-      if (!tabster || !targetDocument) {
+      if (!tabsterRef.current || !targetDocument) {
         return null;
       }
 
       const { container = targetDocument.body } = options;
 
-      return tabster.focusable.findPrev({ currentElement, container });
+      return tabsterRef.current.focusable.findPrev({ currentElement, container });
     },
-    [tabster, targetDocument],
+    [tabsterRef, targetDocument],
   );
 
   return {

packages/react-components/react-tabster/src/hooks/useFocusObserved.ts

@@ -10,24 +10,28 @@ interface UseFocusObservedOptions {
 }
 
 /**
- *
  * @param name - The observed element to focus
- * @returns Function that will focus the
+ * @param options - Options for the focus observed
+ *
+ * @returns Function that will focus an element
  */
 export function useFocusObserved(
   name: string,
   options: UseFocusObservedOptions = {},
 ): () => TabsterTypes.ObservedElementAsyncRequest<boolean> {
   const { timeout = 1000 } = options;
-  const tabster = useTabster();
-
-  const observedAPI = tabster ? getObservedElement(tabster) : null;
+  const observedAPIRef = useTabster(getObservedElement);
 
   return React.useCallback(() => {
-    if (observedAPI) {
-      return observedAPI.requestFocus(name, timeout);
+    const observerAPI = observedAPIRef.current;
+
+    if (observerAPI) {
+      return observerAPI.requestFocus(name, timeout);
     }
 
-    return { result: Promise.resolve(false), cancel: () => null };
-  }, [observedAPI, name, timeout]);
+    return {
+      result: Promise.resolve(false),
+      cancel: () => null,
+    };
+  }, [observedAPIRef, name, timeout]);
 }

packages/react-components/react-tabster/src/hooks/useFocusableGroup.ts

@@ -19,11 +19,7 @@ export interface UseFocusableGroupOptions {
  * @param options - Options to configure keyboard navigation
  */
 export const useFocusableGroup = (options?: UseFocusableGroupOptions): Types.TabsterDOMAttribute => {
-  const tabster = useTabster();
-
-  if (tabster) {
-    getGroupper(tabster);
-  }
+  useTabster(getGroupper);
 
   return useTabsterAttributes({
     groupper: {

packages/react-components/react-tabster/src/hooks/useFocusedElementChange.ts

@@ -1,7 +1,9 @@
-import type { Types as TabsterTypes } from 'tabster';
-
-import { useTabster } from './useTabster';
+import { type Types as TabsterTypes, disposeTabster } from 'tabster';
 import * as React from 'react';
+import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import { useEventCallback } from '@fluentui/react-utilities';
+
+import { createTabsterWithConfig } from './useTabster';
 
 /**
  * Subscribes to the tabster focused element. Calls the callback when the focused element changes.
@@ -10,11 +12,19 @@ import * as React from 'react';
 export function useFocusedElementChange(
   callback: TabsterTypes.SubscribableCallback<HTMLElement | undefined, TabsterTypes.FocusedElementDetail>,
 ) {
-  const tabster = useTabster();
+  const { targetDocument } = useFluent();
+  const listener = useEventCallback(callback);
+
   React.useEffect(() => {
+    const tabster = createTabsterWithConfig(targetDocument);
+
     if (tabster) {
-      tabster.focusedElement.subscribe(callback);
-      return () => tabster.focusedElement.unsubscribe(callback);
+      tabster.focusedElement.subscribe(listener);
+
+      return () => {
+        tabster.focusedElement.unsubscribe(listener);
+        disposeTabster(tabster);
+      };
     }
-  }, [tabster, callback]);
+  }, [listener, targetDocument]);
 }

packages/react-components/react-tabster/src/hooks/useModalAttributes.ts

@@ -46,6 +46,11 @@ const tabsterAccessibleCheck: TabsterTypes.ModalizerElementAccessibleCheck = ele
   return element.hasAttribute(DangerousNeverHiddenAttribute);
 };
 
+function initTabsterModules(tabster: TabsterTypes.TabsterCore) {
+  getModalizer(tabster, undefined, tabsterAccessibleCheck);
+  getRestorer(tabster);
+}
+
 /**
  * Applies modal dialog behaviour through DOM attributes
  * Modal element will focus trap and hide other content on the page
@@ -57,12 +62,9 @@ export const useModalAttributes = (
   options: UseModalAttributesOptions = {},
 ): { modalAttributes: TabsterTypes.TabsterDOMAttribute; triggerAttributes: TabsterTypes.TabsterDOMAttribute } => {
   const { trapFocus, alwaysFocusable, legacyTrapFocus } = options;
-  const tabster = useTabster();
+
   // Initializes the modalizer and restorer APIs
-  if (tabster) {
-    getModalizer(tabster, undefined, tabsterAccessibleCheck);
-    getRestorer(tabster);
-  }
+  useTabster(initTabsterModules);
 
   const id = useId('modal-', options.id);
   const modalAttributes = useTabsterAttributes({

packages/react-components/react-tabster/src/hooks/useObservedElement.ts

@@ -1,12 +1,10 @@
-import { useTabster } from './useTabster';
 import { getObservedElement, Types as TabsterTypes } from 'tabster';
+
+import { useTabster } from './useTabster';
 import { useTabsterAttributes } from './useTabsterAttributes';
 
 export function useObservedElement(name: string | string[]): TabsterTypes.TabsterDOMAttribute {
-  const tabster = useTabster();
-  if (tabster) {
-    getObservedElement(tabster);
-  }
+  useTabster(getObservedElement);
 
   return useTabsterAttributes({ observed: { names: Array.isArray(name) ? name : [name] } });
 }

packages/react-components/react-tabster/src/hooks/useRestoreFocus.ts

@@ -6,11 +6,8 @@ import { useTabster } from './useTabster';
  * @returns Attribute to apply to the target element where focus is restored
  */
 export function useRestoreFocusTarget(): TabsterTypes.TabsterDOMAttribute {
-  const tabster = useTabster();
   // Initializes the restorer API
-  if (tabster) {
-    getRestorer(tabster);
-  }
+  useTabster(getRestorer);
 
   return getTabsterAttribute({ restorer: { type: RestorerTypes.Target } });
 }
@@ -20,11 +17,8 @@ export function useRestoreFocusTarget(): TabsterTypes.TabsterDOMAttribute {
  * @returns Attribute to apply to the element that might lose focus
  */
 export function useRestoreFocusSource(): TabsterTypes.TabsterDOMAttribute {
-  const tabster = useTabster();
   // Initializes the restorer API
-  if (tabster) {
-    getRestorer(tabster);
-  }
+  useTabster(getRestorer);
 
   return getTabsterAttribute({ restorer: { type: RestorerTypes.Source } });
 }

packages/react-components/react-tabster/src/hooks/useTabster.test.ts

@@ -0,0 +1,69 @@
+import { createTabster, disposeTabster } from 'tabster';
+import { renderHook } from '@testing-library/react-hooks';
+import { useTabster } from './useTabster';
+
+jest.mock('tabster', () => ({
+  createTabster: jest.fn(() => 'mock-tabster-instance'),
+  disposeTabster: jest.fn(),
+}));
+
+const createTabsterMock = createTabster as jest.Mock;
+const disposeTabsterMock = disposeTabster as jest.Mock;
+
+describe('useTabster', () => {
+  it('returns a ref to the tabster instance', () => {
+    const { result } = renderHook(() => useTabster());
+
+    expect(createTabsterMock).toHaveBeenCalledTimes(1);
+    expect(result.current).toMatchObject({
+      current: 'mock-tabster-instance',
+    });
+  });
+
+  it('uses the provided factory function to transform the tabster instance', () => {
+    const factoryMock = jest.fn(tabster => ({ customProperty: 'value', tabster }));
+    const { result } = renderHook(() => useTabster(factoryMock));
+
+    expect(factoryMock).toHaveBeenCalledWith('mock-tabster-instance');
+    expect(result.current).toMatchObject({
+      current: { customProperty: 'value', tabster: 'mock-tabster-instance' },
+    });
+  });
+
+  it('disposes tabster when the component unmounts', () => {
+    const { unmount } = renderHook(() => useTabster());
+
+    unmount();
+    expect(disposeTabsterMock).toHaveBeenCalledWith('mock-tabster-instance');
+  });
+
+  describe('environment checks', () => {
+    let originalNodeEnv: string;
+
+    beforeEach(() => {
+      originalNodeEnv = process.env.NODE_ENV ?? '';
+    });
+
+    afterEach(() => {
+      process.env.NODE_ENV = originalNodeEnv;
+    });
+
+    it('throws an error in development if factory function changes', () => {
+      process.env.NODE_ENV = 'development';
+
+      const mockFactory1 = jest.fn(tabster => tabster);
+      const mockFactory2 = jest.fn(tabster => tabster);
+
+      const { result, rerender } = renderHook(({ factory }) => useTabster(factory), {
+        initialProps: { factory: mockFactory1 },
+      });
+
+      rerender({ factory: mockFactory2 });
+
+      expect(result.error).toMatchInlineSnapshot(`
+        [Error: @fluentui/react-tabster: 
+        The factory function passed to useTabster has changed. This should not ever happen.]
+      `);
+    });
+  });
+});