From 7f2e93d38953c98f825768393f90e6023ec2675c Mon Sep 17 00:00:00 2001
From: Lotus CI <ci@lotusguild.org>
Date: Thu, 24 Sep 2026 13:12:13 -0400
Subject: [PATCH] =?UTF-8?q?fix(a11y):=20name=20the=20headless=20modals=20t?=
 =?UTF-8?q?oo=20=E2=80=94=20Seen=20by,=20source,=20file=20viewers=20(#185)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to ce8ed89f for the modals that have no visible heading to
point at: the three "Seen by" reader lists (read-receipt pill, "is
following", message menu), View source, the text/PDF file viewers, the
room-card join error and the user-profile modal get role="dialog",
aria-modal and an aria-label; their traps move focus in (fallbackFocus
on the dialog) where the trap is local.

Verified: the receipt pill opens a "Seen by" dialog with focus on
Close; Escape closes it and focus returns to the pill.

The remaining unnamed Modal/Dialog uses are startup/loading and error
screens (config, feature check, spec versions, client root, password
reset) and wrappers around components that carry their own role (image
viewer).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPmy3tPq869XDW4njjVaKA
---
 .../components/UserRoomProfileRenderer.tsx    | 10 +++++++-
 .../message/content/FileContent.tsx           | 14 +++++++++--
 .../ReadReceiptAvatars.tsx                    | 13 ++++++++--
 src/app/components/room-card/RoomCard.tsx     | 11 ++++++--
 src/app/features/room/RoomViewFollowing.tsx   | 13 ++++++++--
 src/app/features/room/message/Message.tsx     | 25 ++++++++++++++++---
 6 files changed, 73 insertions(+), 13 deletions(-)

diff --git a/src/app/components/UserRoomProfileRenderer.tsx b/src/app/components/UserRoomProfileRenderer.tsx
index 4cef36762..a2f04aa4d 100644
--- a/src/app/components/UserRoomProfileRenderer.tsx
+++ b/src/app/components/UserRoomProfileRenderer.tsx
@@ -71,7 +71,15 @@ function UserRoomProfileContextMenu({ state }: { state: UserRoomProfileState })
       <Overlay open backdrop={<OverlayBackdrop />}>
         <OverlayCenter>
           <FocusTrap focusTrapOptions={focusTrapOptions}>
-            <Modal size="500" style={MOBILE_FULLSCREEN}>
+            <Modal
+              id="user-profile-dialog"
+              role="dialog"
+              aria-modal="true"
+              aria-label="User profile"
+              tabIndex={-1}
+              size="500"
+              style={MOBILE_FULLSCREEN}
+            >
               {/* Full-screen covers the backdrop (no tap-to-dismiss) and the
                   profile has no self-close, so provide an explicit close. */}
               <Header size="600" style={{ flexShrink: 0, paddingRight: config.space.S200 }}>
diff --git a/src/app/components/message/content/FileContent.tsx b/src/app/components/message/content/FileContent.tsx
index 466d06ff7..94b7f1cb5 100644
--- a/src/app/components/message/content/FileContent.tsx
+++ b/src/app/components/message/content/FileContent.tsx
@@ -105,13 +105,18 @@ export function ReadTextFile({ body, mimeType, url, encInfo, renderViewer }: Rea
           <OverlayCenter>
             <FocusTrap
               focusTrapOptions={{
-                initialFocus: false,
+                fallbackFocus: '#file-viewer-2-dialog',
                 onDeactivate: () => setTextViewer(false),
                 clickOutsideDeactivates: true,
                 escapeDeactivates: stopPropagation,
               }}
             >
               <Modal
+                id="file-viewer-2-dialog"
+                role="dialog"
+                aria-modal="true"
+                aria-label={`File: ${body}`}
+                tabIndex={-1}
                 className={ModalWide}
                 size="500"
                 onContextMenu={(evt: React.MouseEvent) => evt.stopPropagation()}
@@ -194,13 +199,18 @@ export function ReadPdfFile({ body, mimeType, url, encInfo, renderViewer }: Read
           <OverlayCenter>
             <FocusTrap
               focusTrapOptions={{
-                initialFocus: false,
+                fallbackFocus: '#file-viewer-1-dialog',
                 onDeactivate: () => setPdfViewer(false),
                 clickOutsideDeactivates: true,
                 escapeDeactivates: stopPropagation,
               }}
             >
               <Modal
+                id="file-viewer-1-dialog"
+                role="dialog"
+                aria-modal="true"
+                aria-label={`File: ${body}`}
+                tabIndex={-1}
                 className={ModalWide}
                 size="500"
                 onContextMenu={(evt: React.MouseEvent) => evt.stopPropagation()}
diff --git a/src/app/components/read-receipt-avatars/ReadReceiptAvatars.tsx b/src/app/components/read-receipt-avatars/ReadReceiptAvatars.tsx
index 1b8f0f684..fab3fc4c6 100644
--- a/src/app/components/read-receipt-avatars/ReadReceiptAvatars.tsx
+++ b/src/app/components/read-receipt-avatars/ReadReceiptAvatars.tsx
@@ -76,13 +76,22 @@ export function ReadReceiptAvatars({
         <OverlayCenter>
           <FocusTrap
             focusTrapOptions={{
-              initialFocus: false,
+              fallbackFocus: '#readreceipt-seenby-dialog',
               onDeactivate: () => setOpen(false),
               clickOutsideDeactivates: true,
               escapeDeactivates: stopPropagation,
             }}
           >
-            <Modal variant="Surface" size="300" style={modalStyle}>
+            <Modal
+              id="readreceipt-seenby-dialog"
+              role="dialog"
+              aria-modal="true"
+              aria-label="Seen by"
+              tabIndex={-1}
+              variant="Surface"
+              size="300"
+              style={modalStyle}
+            >
               <EventReaders room={room} eventId={eventId} requestClose={() => setOpen(false)} />
             </Modal>
           </FocusTrap>
diff --git a/src/app/components/room-card/RoomCard.tsx b/src/app/components/room-card/RoomCard.tsx
index 9683b97d1..d68df382b 100644
--- a/src/app/components/room-card/RoomCard.tsx
+++ b/src/app/components/room-card/RoomCard.tsx
@@ -105,13 +105,20 @@ function ErrorDialog({
         <OverlayCenter>
           <FocusTrap
             focusTrapOptions={{
-              initialFocus: false,
+              fallbackFocus: '#roomcard-error-dialog',
               clickOutsideDeactivates: true,
               onDeactivate: closeError,
               escapeDeactivates: stopPropagation,
             }}
           >
-            <Dialog variant="Surface">
+            <Dialog
+              id="roomcard-error-dialog"
+              role="dialog"
+              aria-modal="true"
+              aria-label={title}
+              tabIndex={-1}
+              variant="Surface"
+            >
               <Box style={{ padding: config.space.S400 }} direction="Column" gap="400">
                 <Box direction="Column" gap="100">
                   <Text>{title}</Text>
diff --git a/src/app/features/room/RoomViewFollowing.tsx b/src/app/features/room/RoomViewFollowing.tsx
index 4e17662dc..b1c2ed5f5 100644
--- a/src/app/features/room/RoomViewFollowing.tsx
+++ b/src/app/features/room/RoomViewFollowing.tsx
@@ -51,13 +51,22 @@ export const RoomViewFollowing = as<'div', RoomViewFollowingProps>(
             <OverlayCenter>
               <FocusTrap
                 focusTrapOptions={{
-                  initialFocus: false,
+                  fallbackFocus: '#following-seenby-dialog',
                   onDeactivate: () => setOpen(false),
                   clickOutsideDeactivates: true,
                   escapeDeactivates: stopPropagation,
                 }}
               >
-                <Modal variant="Surface" size="300" style={modalStyle}>
+                <Modal
+                  id="following-seenby-dialog"
+                  role="dialog"
+                  aria-modal="true"
+                  aria-label="Seen by"
+                  tabIndex={-1}
+                  variant="Surface"
+                  size="300"
+                  style={modalStyle}
+                >
                   <EventReaders room={room} eventId={eventId} requestClose={() => setOpen(false)} />
                 </Modal>
               </FocusTrap>
diff --git a/src/app/features/room/message/Message.tsx b/src/app/features/room/message/Message.tsx
index 1912812e2..c61cba5da 100644
--- a/src/app/features/room/message/Message.tsx
+++ b/src/app/features/room/message/Message.tsx
@@ -290,13 +290,22 @@ export const MessageReadReceiptItem = as<
         <OverlayCenter>
           <FocusTrap
             focusTrapOptions={{
-              initialFocus: false,
+              fallbackFocus: '#message-seenby-dialog',
               onDeactivate: handleClose,
               clickOutsideDeactivates: true,
               escapeDeactivates: stopPropagation,
             }}
           >
-            <Modal variant="Surface" size="300" style={modalStyle}>
+            <Modal
+              id="message-seenby-dialog"
+              role="dialog"
+              aria-modal="true"
+              aria-label="Seen by"
+              tabIndex={-1}
+              variant="Surface"
+              size="300"
+              style={modalStyle}
+            >
               <EventReaders room={room} eventId={eventId} requestClose={handleClose} />
             </Modal>
           </FocusTrap>
@@ -368,13 +377,21 @@ export const MessageSourceCodeItem = as<
         <OverlayCenter>
           <FocusTrap
             focusTrapOptions={{
-              initialFocus: false,
+              fallbackFocus: '#message-source-dialog',
               onDeactivate: handleClose,
               clickOutsideDeactivates: true,
               escapeDeactivates: stopPropagation,
             }}
           >
-            <Modal variant="Surface" size="500">
+            <Modal
+              id="message-source-dialog"
+              role="dialog"
+              aria-modal="true"
+              aria-label="View source"
+              tabIndex={-1}
+              variant="Surface"
+              size="500"
+            >
               <TextViewer
                 name="Source Code"
                 langName="json"