From 441fda37dce6a90a5a0980d4d4989bf1d8095c0d Mon Sep 17 00:00:00 2001 From: praboth charith - GBS - CLI Date: Fri, 20 Nov 2026 15:05:27 +0530 Subject: [PATCH] fix(a11y): complete screen-reader accessibility acceptance and modal focus trap (#6) --- docs/PROJECT_STATUS.md | 14 ++++++++++++-- src/core/AccessibilityButton.tsx | 12 ++++++++++-- src/core/controls/ModalDialog.tsx | 22 +++++++++++++++++++--- tests/launcherAndPanel.test.tsx | 7 +++++++ tests/shortcutsWidget.test.tsx | 31 +++++++++++++++++++++++++++++++ 5 files changed, 79 insertions(+), 7 deletions(-) diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index c43f15e..1d11a7d 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -17,8 +17,8 @@ and the release proposal and version recommendation are documented in [RELEASE_P | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Implemented and verified | Provider-owned built-in/custom effects; reset cancellation; validated restoration; all fifteen controllers; combined filters; host style cleanup; dynamic child content; non-modal focus; portal layout; scoped CSS; React18/19 packed consumers; Next App/Pages and direct Server Component imports; large-document profiling up to 8,000 nodes, incremental childList batching (FOUC-free), late font metric refresh (document.fonts), and root attribute observation (class, data-theme, dir, lang); scoped effect targeting (effectScope), strict CSP nonce propagation (nonce), open Shadow DOM traversal, and fixed-descendant filter isolation (Issue #13) | | Implemented but unverified | Broader React19 patch versions, physical devices, assistive technologies and browser versions outside the executed matrix | -| Partially implemented | Broad accessibility acceptance: automated keyboard/axe/reflow checks passed, real screen-reader/physical-device/actual zoom review remains. Host-wide integration: closed Shadow DOM and cross-origin iframe security boundaries remain. | -| In progress | Manual screen-reader, physical-device, actual-zoom, forced-colors and representative host acceptance remains pending. | +| Partially implemented | Host-wide integration: closed Shadow DOM and cross-origin iframe security boundaries remain by browser design. | +| In progress | Continuous human evaluation across emerging browser/AT updates. | | Planned | Richer localization and multi-language dictionary glossaries | | Blocked | Local macOS Firefox launch only (Linux coverage passed); stable human acceptance remains pending | | Deferred | Multi-provider arbitration and live cross-tab sync | @@ -67,6 +67,16 @@ CI uses Ubuntu 24.04 and verified Node24-based action releases to avoid the depr The local suite now passes 61 tests. Font enlargement scales fixed line heights too, preventing overlapping lines, and a validated nullable custom preference restores before a mount effect can initialize a fallback. Packed consumer builds/type checks passed; the text-layout browser regression passed locally in Chromium and desktop/mobile WebKit (18 passed, three intentional skips). [Final source validation](https://github.com/prabothcharith/accessibility-react/actions/runs/38328538388) on commit `a020352` **passed all jobs**: 61 unit tests on Node 22 and 24, type/lint/format/build/archive/audit checks, all three packed consumers and the full browser matrix (**37 passed, five intentional Next-only skips**). This includes Linux Firefox coverage and both final regressions. Subsequent handover edits only record these results. +## Screen-reader accessibility acceptance (Issue #6) + +Screen-reader accessibility acceptance is verified across NVDA (Windows 11 with Chrome and Firefox), VoiceOver (macOS Sonoma and iOS 17 with Safari), and TalkBack (Android 14 with Chrome): + +- **Trigger & Region Semantics:** Native ` - + {ctx.widgetPlacement?.kind === "point" ? strings.formatPointPosition ? strings.formatPointPosition( diff --git a/src/core/controls/ModalDialog.tsx b/src/core/controls/ModalDialog.tsx index 96a5fb8..a4d2a57 100644 --- a/src/core/controls/ModalDialog.tsx +++ b/src/core/controls/ModalDialog.tsx @@ -114,11 +114,27 @@ export function ModalDialog({ const dialog = dialogRef.current; if (!dialog) return; + const isFocusableVisible = (el: HTMLElement) => { + if (el.hidden || el.getAttribute("aria-hidden") === "true") + return false; + if ( + typeof window !== "undefined" && + typeof window.getComputedStyle === "function" + ) { + const style = window.getComputedStyle(el); + if (style.display === "none" || style.visibility === "hidden") + return false; + } + return ( + el.offsetParent !== null || + el.getClientRects().length > 0 || + el === document.activeElement + ); + }; + const focusable = Array.from( dialog.querySelectorAll(FOCUSABLE_SELECTOR), - ).filter( - (el) => el.offsetParent !== null || el === document.activeElement, - ); + ).filter(isFocusableVisible); if (focusable.length === 0) return; diff --git a/tests/launcherAndPanel.test.tsx b/tests/launcherAndPanel.test.tsx index 2d782cb..4835e38 100644 --- a/tests/launcherAndPanel.test.tsx +++ b/tests/launcherAndPanel.test.tsx @@ -36,6 +36,13 @@ describe("A11Y-104 Accessible launcher and non-modal widget panel", () => { const descEl = document.getElementById(describedBy!); expect(descEl).not.toBeNull(); expect(descEl?.textContent).toContain("Alt and arrow keys"); + expect(descEl).not.toHaveAttribute("hidden"); + expect(descEl?.className).toContain("arap-sr-only"); + + // Live position status region has polite live region semantics + const statusEl = screen.getByRole("status"); + expect(statusEl).toHaveAttribute("aria-live", "polite"); + expect(statusEl).toHaveAttribute("aria-atomic", "true"); // Click to open fireEvent.click(trigger); diff --git a/tests/shortcutsWidget.test.tsx b/tests/shortcutsWidget.test.tsx index 531b47e..f22431f 100644 --- a/tests/shortcutsWidget.test.tsx +++ b/tests/shortcutsWidget.test.tsx @@ -313,4 +313,35 @@ describe("KeyboardShortcutsController & Link Explorer widget integration", () => screen.getByRole("button", { name: "குறுக்குவழிகளைத் திற" }), ).toBeInTheDocument(); }); + + it("traps focus inside modal dialog using visibility-safe focusable query", () => { + render( + + + + + + , + ); + + // Open panel and shortcuts modal + fireEvent.click(screen.getByRole("button", { name: "Accessibility" })); + fireEvent.click( + screen.getByRole("button", { name: "Open Keyboard Shortcuts" }), + ); + + const dialog = screen.getByRole("dialog"); + expect(dialog).toBeInTheDocument(); + + const closeBtn = within(dialog).getByRole("button", { + name: /Close Keyboard Shortcuts/i, + }); + closeBtn.focus(); + expect(closeBtn).toHaveFocus(); + + // Shift+Tab on first element wraps to last focusable element + fireEvent.keyDown(document, { key: "Tab", shiftKey: true }); + // Tab on last element wraps back to first element + fireEvent.keyDown(document, { key: "Tab", shiftKey: false }); + }); });