feat: add useTypingAnnounce hook for managing live regions triggered by user input (#34354)

Author: smhigley

change/@fluentui-react-aria-36d1258c-7b2e-4e3f-a02b-8d3b2e7cc04c.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add useTypingAnnounce hook for managing live regions triggered by user input",
+  "packageName": "@fluentui/react-aria",
+  "email": "sarah.higley@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-components-ddfb2154-93ce-4f5a-b539-e4f4b1ede478.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add useTypingAnnounce hook",
+  "packageName": "@fluentui/react-components",
+  "email": "sarah.higley@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-aria/library/etc/react-aria.api.md

@@ -128,6 +128,9 @@ export function useAriaLiveAnnouncerContextValues_unstable(state: AriaLiveAnnoun
 // @public (undocumented)
 export const useHasParentActiveDescendantContext: () => boolean;
 
+// @public (undocumented)
+export function useTypingAnnounce<TInputElement extends HTMLElement = HTMLElement>(): TypingAnnounceReturn<TInputElement>;
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/react-components/react-aria/library/src/AriaLiveAnnouncer/useAriaLiveAnnouncer.test.tsx

@@ -54,6 +54,7 @@ describe('useAriaLiveAnnouncer', () => {
       const { result } = renderHook(() => useAriaLiveAnnouncer({}), { wrapper: ContextWrapper });
 
       result.current.announce('message loaded');
+      jest.advanceTimersByTime(0);
       expect(innerNode?.innerText).toBe('message loaded' + ANNOUNCE_SUFFIX);
     });
 
@@ -105,6 +106,19 @@ describe('useAriaLiveAnnouncer', () => {
       );
     });
 
+    it('should handle batched messages in the same tick, and announce only the last', () => {
+      const appendChild = jest.spyOn(liveRegionNode!, 'appendChild');
+      const { result } = renderHook(() => useAriaLiveAnnouncer({}), { wrapper: ContextWrapper });
+
+      result.current.announce('message loaded', { batchId: 'test' });
+      result.current.announce('message reloaded', { batchId: 'test' });
+      result.current.announce('message revolutions', { batchId: 'test' });
+      jest.advanceTimersByTime(100);
+
+      expect(appendChild).toHaveBeenCalledTimes(1);
+      expect(innerNode?.innerText).toBe('message revolutions' + ANNOUNCE_SUFFIX);
+    });
+
     it('should announce batched and unbatched messages', () => {
       const { result } = renderHook(() => useAriaLiveAnnouncer({}), { wrapper: ContextWrapper });
 
@@ -123,6 +137,7 @@ describe('useAriaLiveAnnouncer', () => {
       const { result } = renderHook(() => useAriaLiveAnnouncer({}), { wrapper: ContextWrapper });
 
       result.current.announce('message resurrections');
+      jest.advanceTimersByTime(0);
       expect(innerNode?.innerText).toBe('message resurrections' + ANNOUNCE_SUFFIX);
 
       jest.advanceTimersByTime(ANNOUNCE_TIMEOUT);

packages/react-components/react-aria/library/src/AriaLiveAnnouncer/useDomAnnounce.ts

@@ -86,7 +86,10 @@ export const useDomAnnounce_unstable = (): AriaLiveAnnounceFn => {
       }
     };
 
-    runCycle();
+    // Run the first cycle with a 0 timeout to ensure multiple messages in the same tick are handled
+    timeoutRef.current = setAnnounceTimeout(() => {
+      runCycle();
+    }, 0);
   }, [clearAnnounceTimeout, messageQueue, setAnnounceTimeout, targetDocument]);
 
   const announce: AriaLiveAnnounceFn = React.useCallback(

packages/react-components/react-aria/library/src/index.ts

@@ -33,3 +33,5 @@ export {
   useAriaLiveAnnouncerContextValues_unstable,
 } from './AriaLiveAnnouncer/index';
 export type { AriaLiveAnnouncerProps, AriaLiveAnnouncerState } from './AriaLiveAnnouncer/index';
+
+export { useTypingAnnounce } from './useTypingAnnounce/index';

packages/react-components/react-aria/library/src/useTypingAnnounce/index.ts

@@ -0,0 +1 @@
+export { useTypingAnnounce } from './useTypingAnnounce';

packages/react-components/react-aria/library/src/useTypingAnnounce/useTypingAnnounce.ts

@@ -0,0 +1,83 @@
+import * as React from 'react';
+import { useTimeout } from '@fluentui/react-utilities';
+import { useAnnounce, useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import type { AnnounceOptions } from '@fluentui/react-shared-contexts';
+import { AriaLiveAnnounceFn } from '../AriaLiveAnnouncer/AriaLiveAnnouncer.types';
+
+type Message = {
+  message: string;
+  options: AnnounceOptions;
+};
+
+const valueMutationOptions = {
+  attributes: true,
+  subtree: true,
+  characterData: true,
+  attributeFilter: ['value'],
+};
+
+interface TypingAnnounceReturn<TInputElement extends HTMLElement = HTMLElement> {
+  typingAnnounce: AriaLiveAnnounceFn;
+  inputRef: React.RefObject<TInputElement>;
+}
+
+export function useTypingAnnounce<
+  TInputElement extends HTMLElement = HTMLElement,
+>(): TypingAnnounceReturn<TInputElement> {
+  const { targetDocument } = useFluent();
+  const { announce } = useAnnounce();
+
+  const inputRef = React.useRef<TInputElement>(null);
+  const observer = React.useRef<MutationObserver>();
+  const [setTypingTimeout, clearTypingTimeout] = useTimeout();
+  const messageQueue = React.useRef<Message[]>([]);
+
+  const callback: MutationCallback = React.useCallback(
+    (mutationList, mutationObserver) => {
+      setTypingTimeout(() => {
+        messageQueue.current.forEach(({ message, options }) => {
+          announce(message, options);
+        });
+        messageQueue.current.length = 0;
+        mutationObserver.disconnect();
+      }, 500);
+    },
+    [announce, setTypingTimeout],
+  );
+
+  const typingAnnounce: AriaLiveAnnounceFn = React.useCallback(
+    (message: string, options: AnnounceOptions = {}) => {
+      messageQueue.current.push({ message, options });
+
+      if (inputRef.current && observer.current) {
+        observer.current.observe(inputRef.current, valueMutationOptions);
+      }
+
+      setTypingTimeout(() => {
+        observer.current && callback([], observer.current);
+      }, 500);
+    },
+    [callback, inputRef, setTypingTimeout],
+  );
+
+  React.useEffect(() => {
+    const win = targetDocument?.defaultView;
+    if (!win) {
+      return;
+    }
+
+    if (!observer.current) {
+      observer.current = new win.MutationObserver(callback);
+    }
+
+    return () => {
+      // Clean up the observer when the component unmounts
+      if (observer.current) {
+        observer.current.disconnect();
+        clearTypingTimeout();
+      }
+    };
+  }, [callback, clearTypingTimeout, targetDocument]);
+
+  return { typingAnnounce, inputRef };
+}

packages/react-components/react-aria/stories/src/AriaLiveAnnouncer/AriaLiveAnnouncerDescription.md

@@ -1,6 +1,6 @@
 `AriaLiveAnnouncer` provides a sample implementation of an `aria-live` region that can be used to announce messages to screen readers.
 
-It injects announcements into the DOM, and also exposes a function (to its children in a React tree) that can be used to announce messages. It's designed to be used with `useAnnounce()` hook.
+It injects announcements into the DOM, and also exposes a function (to its children in a React tree) that can be used to announce messages. It's designed to be used with `useAnnounce()` or `useTypingAnnounce()` hooks.
 
 For debugging information, check our [Debugging Notifications](./?path=/docs/concepts-developer-accessibility-notification-debugging--docs) docs page.
 

packages/react-components/react-aria/stories/src/UseTypingAnnounce/UseTypingAnnounceContentEditable.stories.tsx

@@ -0,0 +1,74 @@
+import * as React from 'react';
+import {
+  AriaLiveAnnouncer,
+  Field,
+  JSXElement,
+  makeStyles,
+  tokens,
+  useId,
+  useTypingAnnounce,
+} from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  contentEditable: {
+    border: `1px solid ${tokens.colorNeutralStroke1}`,
+    borderRadius: '4px',
+    padding: '0.5em',
+  },
+});
+
+const charCountMessage = (count: number) => {
+  // the threshold for announcing character count updates is 10 characters
+  const threshold = 10;
+
+  // the maxLength is 100
+  const maxLength = 100;
+
+  if (count >= maxLength) {
+    return `You have reached the maximum character limit, ${maxLength}`;
+  } else if (maxLength - count === 1) {
+    return `You have 1 character remaining`;
+  } else if (maxLength - count <= threshold) {
+    return `You have ${maxLength - count} characters remaining`;
+  } else {
+    return undefined;
+  }
+};
+
+export const ContentEditable = (): JSXElement => {
+  const [count, setCount] = React.useState(0);
+  const styles = useStyles();
+
+  const announceId = useId('charCount');
+
+  const { typingAnnounce, inputRef } = useTypingAnnounce();
+
+  const onInput = (ev: React.FormEvent<HTMLSpanElement>) => {
+    const charCount = (ev.target as HTMLSpanElement).textContent?.length ?? 0;
+    setCount(charCount);
+
+    const message = charCountMessage(charCount);
+    if (message) {
+      // pass typingAnnounce a batchId to ensure new charCount updates override old ones
+      typingAnnounce(message, { batchId: announceId });
+    }
+  };
+
+  return (
+    <AriaLiveAnnouncer>
+      <Field label="A contenteditable div with a maxlength of 100" hint={`${count}/100`}>
+        {fieldProps => (
+          <span contentEditable ref={inputRef} onInput={onInput} className={styles.contentEditable} {...fieldProps} />
+        )}
+      </Field>
+    </AriaLiveAnnouncer>
+  );
+};
+
+ContentEditable.parameters = {
+  docs: {
+    description: {
+      story: `Updates on remaining characters will begin being announced once you are within 10 characters of the max length.`,
+    },
+  },
+};