microsoft · compulim · Nov 26, 2025 · Nov 26, 2025 · Nov 26, 2025 · Nov 26, 2025
diff --git a/__tests__/html2/accessibility/scanMode/ideal.html b/__tests__/html2/accessibility/scanMode/ideal.html
@@ -0,0 +1,348 @@
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <link href="/assets/index.css" rel="stylesheet" type="text/css" />
+    <style type="text/css">
+      body {
+        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+      }
+
+      .chat-history__body {
+        display: flex;
+        flex-direction: column;
+        gap: 12px;
+        padding: 6px;
+      }
+
+      /* Can we eliminate .chat-history:focus? It doesn't follow BEM. */
+      .chat-history:focus .chat-message__is-active {
+        outline: dashed 2px black;
+        outline-offset: 2px;
+      }
+
+      .chat-message {
+        background-color: White;
+        border: solid 1px #ddd;
+        border-radius: 8px;
+        box-shadow: 0 0 10px rgba(0, 0, 0, 0.05);
+        padding: 8px;
+      }
+
+      .chat-message__header {
+        color: #999;
+        font-size: smaller;
+        font-weight: lighter;
+        margin-block-start: 0;
+        margin-block-end: 0.2em;
+      }
+
+      .chat-message__content > .focus-trap > p:first-of-type {
+        margin-block-start: 0;
+      }
+
+      .chat-message__content > .focus-trap > p:last-of-type {
+        margin-block-end: 0;
+      }
+
+      .chat-message__content,
+      .focus-trap {
+        /* These elements are meaningless in CSS world, adding "display: contents" to save some CPUs. */
+        display: contents;
+      }
+
+      .send-box {
+        margin: 6px;
+      }
+    </style>
+  </head>
+  <body>
+    <main></main>
+    <script type="importmap">
+      {
+        "imports": {
+          "classnames": "https://esm.sh/classnames",
+          "jest-mock": "https://esm.sh/jest-mock",
+          "react": "https://esm.sh/react",
+          "react-dom": "https://esm.sh/react-dom"
+        }
+      }
+    </script>
+    <script crossorigin="anonymous" src="https://esm.sh/tsx" type="module"></script>
+    <script type="text/babel">
+      import cx from 'classnames';
+      import { useRefFrom } from 'https://esm.sh/use-ref-from';
+      import { useStateWithRef } from 'https://esm.sh/use-state-with-ref';
+      import { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+      import { createRoot } from 'react-dom/client';
+
+      const FOCUSABLE_SELECTOR_QUERY = [
+        'a[href]',
+        'button:not([disabled])',
+        'textarea:not([disabled])',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])'
+      ].join(',');
+
+      function usePrevious(value) {
+        const previousRef = useRef();
+
+        useEffect(() => {
+          previousRef.current = value;
+        });
+
+        return previousRef.current;
+      }
+
+      // TODO: Use our own implementation of <FocusTrap>, we have better UX:
+      //       - Save last focus
+      //       - When an element become non-focusable
+      //       However, this implementation is better at:
+      //       - Handle "inert" attribute
+      //       - Handle invisible element (element without `offsetParent`)
+      function FocusTrap({ children, onLeave }) {
+        const onLeaveRef = useRefFrom(onLeave);
+        const rootRef = useRef();
+
+        const handleKeyDown = useCallback(
+          event => {
+            const container = rootRef.current;
+
+            if (!container) {
+              return;
+            }
+
+            if (event.key === 'Tab') {
+              const focusables = Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR_QUERY)).filter(
+                element => !element.closest('[inert]') && element.offsetParent
+              );
+
+              if (focusables.length === 0) {
+                return;
+              }
+
+              const firstElement = focusables[0];
+              const lastElement = focusables.at(-1);
+
+              if (event.shiftKey && document.activeElement === firstElement) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                lastElement.focus();
+              } else if (!event.shiftKey && document.activeElement === lastElement) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                firstElement.focus();
+              }
+            } else if (event.key === 'Escape') {
+              event.stopPropagation();
+
+              onLeaveRef.current?.();
+            }
+          },
+          [onLeaveRef]
+        );
+
+        return (
+          <div className="focus-trap" onKeyDown={handleKeyDown} ref={rootRef}>
+            {children}
+          </div>
+        );
+      }
+
+      function ChatMessage({ abstract, activeMode, children, index, onLeave, onRequestFocus }) {
+        const bodyRef = useRef();
+        const contentId = useMemo(() => crypto.randomUUID(), []);
+        const headerId = useMemo(() => crypto.randomUUID(), []);
+        const indexRef = useRefFrom(index);
+        const onLeaveRef = useRefFrom(onLeave);
+        const onRequestFocusRef = useRefFrom(onRequestFocus);
+
+        const isFocused = activeMode === 'focus';
+        const wasFocused = usePrevious(isFocused);
+        const becomingFocused = !wasFocused && isFocused;
+
+        const isFocusedRef = useRefFrom(isFocused);
+
+        const handleKeyDown = useCallback(
+          event => {
+            if (isFocusedRef.current) {
+              event.stopPropagation();
+            }
+
+            if (event.key === 'Escape') {
+              event.stopPropagation();
+
+              onLeaveRef.current?.();
+            }
+          },
+          [onLeaveRef]
+        );
+
+        useEffect(() => {
+          if (becomingFocused) {
+            bodyRef.current?.focus();
+          }
+        }, [becomingFocused]);
+
+        const handleHeaderClick = useCallback(
+          event => onRequestFocusRef.current?.(indexRef.current),
+          [indexRef, onRequestFocusRef]
+        );
+
+        return (
+          <article // Required: children of role="feed" must be role="article".
+            aria-labelledby={headerId} // Required: we just want screen reader to narrate header. Without this, it will narrate the whole content.
+            className={cx('chat-message', { 'chat-message__is-active': activeMode === 'active' })}
+            id={`chat-message__index-${index}`}
+          >
+            <h4
+              className="chat-message__header"
+              id={headerId}
+              // Narrator UX: in scan mode, when user press ENTER, we will get onClick and we can use it to focus into the message.
+              //              However, this item should be hidden as we want to prevent mouse clicks.
+              onClick={handleHeaderClick}
+            >
+              {abstract}
+            </h4>
+            <div
+              aria-labelledby={contentId} // Narrator quirks: without aria-labelledby, after pressing ENTER and focus on this element, Narrator will say nothing.
+              className="chat-message__body"
+              inert={!isFocused} // Required: if the element is not focused, its contents should not be tabbable.
+              onKeyDown={handleKeyDown}
+              ref={bodyRef}
+              role={isFocused ? 'document' : undefined} // Required: as instructed by C+AI accessibility team: after pressing ENTER, add role="document" and focus on the element, screen reader should change to scan/browse mode.
+              tabindex={isFocused ? -1 : undefined} // Required: as instructed by C+AI accessibility team: after pressing ENTER, add role="document" and focus on the element, screen reader should change to scan/browse mode.
+            >
+              <div className="chat-message__content" id={contentId}>
+                <FocusTrap onLeave={onLeave}>{children}</FocusTrap>
+              </div>
+            </div>
+          </article>
+        );
+      }
+
+      function ChatHistory({ onLeave }) {
+        const [activeMessageIndex, setActiveMessageIndex] = useState(0);
+        const [isFocused, setIsFocused, isFocusedRef] = useStateWithRef(false);
+        const onLeaveRef = useRefFrom(onLeave);
+        const rootRef = useRef();
+
+        const handleKeyDown = useCallback(
+          event => {
+            if (event.key === 'ArrowUp') {
+              event.stopPropagation();
+
+              setActiveMessageIndex(index => Math.max(0, index - 1));
+            } else if (event.key === 'ArrowDown') {
+              event.stopPropagation();
+
+              setActiveMessageIndex(index => Math.min(1, index + 1));
+            } else if (event.key === 'Enter') {
+              event.stopPropagation();
+
+              setIsFocused(true);
+            } else if (event.key === 'Escape') {
+              // We like this, when pressing ESCAPE key on chat history, send the focus to send box.
+              setIsFocused(false);
+
+              onLeaveRef.current?.();
+            }
+          },
+          [isFocusedRef, onLeaveRef, setActiveMessageIndex, setIsFocused]
+        );
+
+        const handleMessageLeave = useCallback(() => {
+          rootRef.current?.focus();
+
+          setIsFocused(false);
+        }, [rootRef, setIsFocused]);
+
+        const handleMessageRequestFocus = useCallback(
+          index => {
+            setActiveMessageIndex(index);
+            setIsFocused(true);
+          },
+          [setActiveMessageIndex, setIsFocused]
+        );
+
+        return (
+          <div
+            aria-activedescendant={`chat-message__index-${activeMessageIndex}`} // Matter of taste: we are using active descendant to control focus, instead of roving tab index.
+            className="chat-history"
+            onKeyDown={handleKeyDown}
+            ref={rootRef}
+            role="group" // Required: aria-activedescendant is only available for role="group".
+            tabindex="0" // Required: container of the active descendant must be focusable.
+          >
+            <section
+              className="chat-history__body"
+              role="feed" // Required: we are using role="feed/article" to represent the chat thread.
+            >
+              <ChatMessage
+                abstract="Bot said: Hello, World!" // Matter of taste on how to abstract the text: this is for screen reader user pressing H key to quickly jump between messages.
+                activeMode={activeMessageIndex === 0 ? (isFocused ? 'focus' : 'active') : undefined}
+                index={0}
+                onLeave={activeMessageIndex === 0 ? handleMessageLeave : undefined}
+                onRequestFocus={handleMessageRequestFocus}
+              >
+                <p>Hello, World!</p>
+                <p>
+                  Click <a href="https://bing.com/">this link</a> for more details.
+                </p>
+              </ChatMessage>
+              <ChatMessage
+                abstract="You said: Aloha!"
+                activeMode={activeMessageIndex === 1 ? (isFocused ? 'focus' : 'active') : undefined}
+                index={1}
+                onLeave={activeMessageIndex === 1 ? handleMessageLeave : undefined}
+                onRequestFocus={handleMessageRequestFocus}
+              >
+                <p>Aloha!</p>
+              </ChatMessage>
+            </section>
+          </div>
+        );
+      }
+
+      const SendBox = forwardRef(function SendBox(_, ref) {
+        const handleSubmit = useCallback(event => {
+          event.preventDefault();
+        }, []);
+
+        return (
+          <form className="send-box" onSubmit={handleSubmit}>
+            <textarea className="send-box__text-box" placeholder="Type a message" ref={ref} />
+          </form>
+        );
+      });
+
+      function ChatApp() {
+        const sendBoxRef = useRef();
+
+        const handleChatHistoryLeave = useCallback(() => {
+          sendBoxRef.current?.focus();
+        }, [sendBoxRef]);
+
+        return (
+          <div
+            className="chat-app"
+            role="application" // Required: role="document" will only work when its container has role="application".
+          >
+            <ChatHistory onLeave={handleChatHistoryLeave} />
+            <SendBox ref={sendBoxRef} />
+          </div>
+        );
+      }
+
+      const mainElement = document.querySelector('main');
+
+      mainElement && createRoot(mainElement).render(<ChatApp />);
+
+      setTimeout(() => {
+        document.querySelector('textarea')?.focus();
+      }, 100);
+    </script>
+  </body>
+</html>