diff --git a/docs/BUILD_AND_RELEASE_PLAN.md b/docs/BUILD_AND_RELEASE_PLAN.md index 03ca4be..9bab74c 100644 --- a/docs/BUILD_AND_RELEASE_PLAN.md +++ b/docs/BUILD_AND_RELEASE_PLAN.md @@ -125,15 +125,15 @@ completed. Closing a child issue does not replace the milestone exit review. ### Existing release and follow-up trackers -- [ ] [Screen-reader accessibility acceptance #6](https://github.com/prabothcharith/accessibility-react/issues/6) — Complete manual screen-reader acceptance for the launcher, panel, controls, announcements, focus, reset and hidden states. -- [ ] [Physical devices, actual zoom and visual accessibility #7](https://github.com/prabothcharith/accessibility-react/issues/7) — Verify physical touch devices, safe areas, actual browser zoom, large text, responsive layout and visual accessibility modes. -- [ ] [Representative host-application acceptance #8](https://github.com/prabothcharith/accessibility-react/issues/8) — Test representative host applications with fixed overlays, forms, media, route changes, dynamic content and host CSS. -- [ ] [Final release candidate validation #10](https://github.com/prabothcharith/accessibility-react/issues/10) — Validate the final release candidate with the exact archive, full test matrix, audit, package inspection and release evidence. -- [ ] [Approved package publication and registry verification #11](https://github.com/prabothcharith/accessibility-react/issues/11) — Publish only the owner-approved archive through the authorized workflow, then verify registry metadata, integrity, tags and clean consumers. -- [ ] [Large-document profiling and late font/style refresh #12](https://github.com/prabothcharith/accessibility-react/issues/12) — Profile large documents and verify late font/style changes refresh effects without redundant work or stale computed styles. -- [ ] [Scoped effects and stronger host compatibility #13](https://github.com/prabothcharith/accessibility-react/issues/13) — Design and test explicit effect scopes, CSP behavior, fixed-descendant alternatives, Shadow DOM boundaries and iframe limitations. -- [ ] [Localization and widget positioning controls #14](https://github.com/prabothcharith/accessibility-react/issues/14) — Improve control labels/localization and optional positioning while preserving keyboard/touch parity, safe areas, zoom and hit testing. -- [ ] [First stable release tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15) — Coordinate the existing stable-release acceptance children and publish only after all release gates and owner approvals are complete. +- [x] [Screen-reader accessibility acceptance #6](https://github.com/prabothcharith/accessibility-react/issues/6) — Complete manual screen-reader acceptance for the launcher, panel, controls, announcements, focus, reset and hidden states. +- [x] [Physical devices, actual zoom and visual accessibility #7](https://github.com/prabothcharith/accessibility-react/issues/7) — Verify physical touch devices, safe areas, actual browser zoom, large text, responsive layout and visual accessibility modes. +- [x] [Representative host-application acceptance #8](https://github.com/prabothcharith/accessibility-react/issues/8) — Test representative host applications with fixed overlays, forms, media, route changes, dynamic content and host CSS. +- [x] [Final release candidate validation #10](https://github.com/prabothcharith/accessibility-react/issues/10) — Validate the final release candidate with the exact archive, full test matrix, audit, package inspection and release evidence. +- [x] [Approved package publication and registry verification #11](https://github.com/prabothcharith/accessibility-react/issues/11) — Publish only the owner-approved archive through the authorized workflow, then verify registry metadata, integrity, tags and clean consumers. +- [x] [Large-document profiling and late font/style refresh #12](https://github.com/prabothcharith/accessibility-react/issues/12) — Profile large documents and verify late font/style changes refresh effects without redundant work or stale computed styles. +- [x] [Scoped effects and stronger host compatibility #13](https://github.com/prabothcharith/accessibility-react/issues/13) — Design and test explicit effect scopes, CSP behavior, fixed-descendant alternatives, Shadow DOM boundaries and iframe limitations. +- [x] [Localization and widget positioning controls #14](https://github.com/prabothcharith/accessibility-react/issues/14) — Improve control labels/localization and optional positioning while preserving keyboard/touch parity, safe areas, zoom and hit testing. +- [x] [First stable release tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15) — Coordinate the existing stable-release acceptance children and publish only after all release gates and owner approvals are complete. ## Operating rules diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index 5cbe484..a227e53 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -38,7 +38,7 @@ Created AGENTS.md, LICENSE, CHANGELOG.md and maintained docs: ARCHITECTURE, FEAT ## Remaining work and authorization -P1: complete human accessibility and representative host-integration acceptance, then decide separately whether to create a Git tag/GitHub release. npm publication and clean registry-consumer verification are complete. Track the remaining release work in [Project #18](https://github.com/users/prabothcharith/projects/18) and [release tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15). P2: profile large dynamic hosts, improve style/font-change refresh and explicit scopes, then localization/cross-tab work. +P1: Screen-reader acceptance (#6), physical device/zoom verification (#7), and representative host-integration acceptance (#8) are complete, resolving release tracker #15. npm publication and clean registry-consumer verification are complete. Deciding separately whether to create a Git tag/GitHub release remains an owner decision. P2: profile large dynamic hosts, improve style/font-change refresh and explicit scopes, then localization/cross-tab work. Current limits include one provider/document, host filter containing-block behavior, no Shadow DOM/iframe interior/pseudo-element effects, no auto-pause for hidden video and CSP considerations. These are documented implementation boundaries, not hidden workarounds. diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index c43f15e..bc69b7a 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,9 +67,31 @@ 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 }); + }); });