Added accessible announcement for the TextAnnotatorPopup appearance

packages/text-annotator-react/package.json

@@ -47,8 +47,10 @@
     "@annotorious/core": "^3.0.14",
     "@annotorious/react": "^3.0.14",
     "@floating-ui/react": "^0.27.1",
+    "@react-aria/live-announcer": "^3.3.4",
     "@recogito/text-annotator": "3.0.0-rc.53",
     "@recogito/text-annotator-tei": "3.0.0-rc.53",
-    "CETEIcean": "^1.9.3"
+    "CETEIcean": "^1.9.3",
+    "unique-random": "^4.0.0"
   }
-}
+}

packages/text-annotator-react/src/TextAnnotationPopup/TextAnnotationPopup.tsx

@@ -1,4 +1,5 @@
-import { ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import { FC, ReactNode, useCallback, useRef, useEffect, useMemo, useState } from 'react';
+
 import { useAnnotator, useSelection } from '@annotorious/react';
 import {
   NOT_ANNOTATABLE_CLASS,
@@ -7,7 +8,6 @@ import {
   type TextAnnotator,
 } from '@recogito/text-annotator';
 
-import { isMobile } from './isMobile';
 import {
   arrow,
   autoUpdate,
@@ -25,10 +25,15 @@ import {
   useRole
 } from '@floating-ui/react';
 
+import { isMobile } from './isMobile';
+import { useAnnouncePopupNavigation } from '../hooks';
+
 import './TextAnnotationPopup.css';
 
 interface TextAnnotationPopupProps {
 
+  ariaNavigationMessage?: string;
+
   ariaCloseWarning?: string;
 
   arrow?: boolean;
@@ -55,7 +60,7 @@ const toViewportBounds = (annotationBounds: DOMRect, container: HTMLElement): DO
   return new DOMRect(left + containerBounds.left, top + containerBounds.top, right - left, bottom - top);
 }
 
-export const TextAnnotationPopup = (props: TextAnnotationPopupProps) => {
+export const TextAnnotationPopup: FC<TextAnnotationPopupProps> = (props) => {
 
   const r = useAnnotator<TextAnnotator>();
 
@@ -64,6 +69,14 @@ export const TextAnnotationPopup = (props: TextAnnotationPopupProps) => {
   const annotation = selected[0]?.annotation;
 
   const [isOpen, setOpen] = useState(selected?.length > 0);
+  const handleClose = () => r?.cancelSelected();
+
+  const [isFocused, setFocused] = useState(false);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  useEffect(() => {
+    if (!isOpen) handleBlur();
+  }, [isOpen, handleBlur]);
 
   const arrowRef = useRef(null);
 
@@ -73,7 +86,7 @@ export const TextAnnotationPopup = (props: TextAnnotationPopupProps) => {
     onOpenChange: (open, _event, reason) => {
       if (!open && (reason === 'escape-key' || reason === 'focus-out')) {
         setOpen(open);
-        r?.cancelSelected();
+        handleClose();
       }
     },
     middleware: [
@@ -143,7 +156,15 @@ export const TextAnnotationPopup = (props: TextAnnotationPopupProps) => {
     return (event?.type === 'keyup' || event?.type === 'contextmenu' || isMobile()) ? -1 : 0;
   }, [event]);
 
-  const onClose = () => r?.cancelSelected();
+  /**
+   * Announce the navigation hint only on the keyboard selection,
+   * because the focus isn't shifted to the popup automatically then
+   */
+  useAnnouncePopupNavigation({
+    disabled: isFocused,
+    floatingOpen: isOpen,
+    message: props.ariaNavigationMessage,
+  });
 
   return isOpen && annotation ? (
     <FloatingPortal>
@@ -157,21 +178,24 @@ export const TextAnnotationPopup = (props: TextAnnotationPopupProps) => {
           className={`a9s-popup r6o-popup annotation-popup r6o-text-popup ${NOT_ANNOTATABLE_CLASS}`}
           ref={refs.setFloating}
           style={floatingStyles}
-          {...getFloatingProps(getStopEventsPropagationProps())}>
+          {...getFloatingProps({
+            onFocus: handleFocus,
+            onBlur: handleBlur,
+            ...getStopEventsPropagationProps()
+          })}>
           {props.popup({
             annotation: selected[0].annotation,
             editable: selected[0].editable,
             event
           })}
-
           {props.arrow && (
             <FloatingArrow
               ref={arrowRef}
               context={context}
               {...(props.arrowProps || {})} />
           )}
 
-          <button className="r6o-popup-sr-only" aria-live="assertive" onClick={onClose}>
+          <button className="r6o-popup-sr-only" aria-live="assertive" onClick={handleClose}>
             {props.ariaCloseWarning || 'Click or leave this dialog to close it.'}
           </button>
         </div>

packages/text-annotator-react/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from './useAnnouncePopupNavigation';

packages/text-annotator-react/src/hooks/useAnnouncePopupNavigation.ts

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+
+import { Origin, useAnnotationStore, useSelection } from '@annotorious/react';
+import type { TextAnnotation } from '@recogito/text-annotator';
+import { announce, destroyAnnouncer } from '@react-aria/live-announcer';
+import { exhaustiveUniqueRandom } from 'unique-random';
+
+interface AnnouncePopupOpeningArgs {
+    message?: string;
+    idle?: number;
+    floatingOpen: boolean;
+    floatingFocused?: boolean;
+    disabled?: boolean;
+}
+
+export const useAnnouncePopupNavigation = (args: AnnouncePopupOpeningArgs) => {
+  const {
+    message = 'Press Tab to move to Notes Dialog',
+    idle = 700,
+    floatingOpen,
+    disabled = false
+  } = args;
+
+  const store = useAnnotationStore();
+  const { event } = useSelection<TextAnnotation>();
+
+  // Generate random numbers that do not repeat until the entire 1-10000 range has appeared
+  const uniqueRandom = useCallback(exhaustiveUniqueRandom(1, 10000), []);
+
+  /**
+   * Initialize the `LiveAnnouncer` class and
+   * its `polite` announcements live area
+   */
+  useLayoutEffect(() => {
+    if (disabled || !message) return;
+
+    announce('', 'polite');
+    return () => destroyAnnouncer();
+  }, [disabled, message]);
+
+  /**
+   * Screen reader requires messages to always be unique!
+   * Otherwise, the hint will be announced once per page.
+   */
+  const announcementSeed = useMemo(() => floatingOpen ? uniqueRandom() : 0, [floatingOpen]);
+
+  const announcePopupNavigation = useCallback(() => {
+    /**
+     * To imitate the uniqueness of the announced message
+     * w/o mutating it - we can append spaces at the end.
+     */
+    const uniqueSpaces = Array.from({ length: announcementSeed }).map(() => ' ').join('');
+    announce(`${message} ${uniqueSpaces}`, 'polite');
+  }, [message, announcementSeed]);
+
+  const idleTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (disabled || !floatingOpen || !message) return;
+
+    const scheduleIdleAnnouncement = () => {
+      clearTimeout(idleTimeoutRef.current);
+      idleTimeoutRef.current = setTimeout(announcePopupNavigation, idle);
+    };
+
+    scheduleIdleAnnouncement();
+    store.observe(scheduleIdleAnnouncement, { origin: Origin.LOCAL });
+
+    return () => {
+      clearTimeout(idleTimeoutRef.current);
+      store.unobserve(scheduleIdleAnnouncement);
+    };
+  }, [disabled, floatingOpen, event?.type, message, announcePopupNavigation, store]);
+
+};

packages/text-annotator-react/src/index.ts

@@ -1,4 +1,5 @@
 export * from './tei';
+export * from './hooks';
 export * from './TextAnnotator';
 export * from './TextAnnotationPopup';
 export * from './TextAnnotatorPlugin';