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 1/3] 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 }); + }); }); From 705e8f01d5a82c5917a9b41a435be30daa926568 Mon Sep 17 00:00:00 2001 From: praboth charith - GBS - CLI Date: Fri, 20 Nov 2026 15:08:11 +0530 Subject: [PATCH 2/3] docs: complete representative host-application acceptance (#8) --- docs/PROJECT_STATUS.md | 16 ++++++++++++++-- docs/ROADMAP.md | 2 +- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index 1d11a7d..bc69b7a 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -77,9 +77,21 @@ Screen-reader accessibility acceptance is verified across NVDA (Windows 11 with - **Modal Dialog Focus Trap:** Modals (Keyboard Shortcuts, Dictionary, Translation, Page Navigator) trap Tab and Shift+Tab focus using visibility-safe element queries and return focus to invoking triggers on Escape/Close without leaking focus into background elements. - **Zero Automated Violations:** Continuous `@axe-core/playwright` audits across all themes and responsive viewports yield zero detectable WCAG 2.0/2.1/2.2 A/AA violations. +## Representative host-application acceptance (Issue #8) + +Representative host-application acceptance is verified across clean packed consumers in production builds: + +- **Host Applications Tested:** React 18.3.1 (Vite), React 19.2.0 (Tailwind CSS 3 Vite), Next.js 16.2.10 (App Router, Pages Router, and direct Server Component imports). +- **Sticky & Fixed Overlay Isolation:** Scoped effects (`effectScope`) and fixed-descendant filter isolation ensure host navigation bars and fixed overlays are not distorted by CSS containing block creation (Issue #13). +- **Dynamic Content & Font Loading:** Incremental mutation handling without FOUC, late font loading via `document.fonts`, and root attribute observation (`class`, `data-theme`, `dir`, `lang`) without observer feedback loops (Issue #12). +- **Forms & Interactive Controls:** Protected form controls, buttons, links, tables, code blocks, and math from unwanted font/spacing alterations. +- **Media Hiding Layout Retention:** Verified that HTML images, pictures, CSS backgrounds, and video elements retain their dimensions when hidden and playback continues non-destructively in the background without layout shifts (Issues #194, #201, #204, #206). +- **Storage Resilience & Lifecycle Cleanup:** Confirmed fallback to in-memory state on blocked or corrupt `localStorage`, clean cleanup upon provider unmount, and zero orphaned style sheets or detached DOM listeners. +- **Resolved Sub-issues:** #187 (host translation adapter), #188 (dictionary lookup), #201 (figure decorative markers & Google Translate adapter). + ## Known limits and release gates -1. **Human accessibility testing pending:** VoiceOver/NVDA, physical touch devices, forced-colors visual review, browser zoom 200/400%. Automated axe and emulation do not establish WCAG conformance. +1. **Human accessibility testing baseline completed:** Screen-reader acceptance (VoiceOver/NVDA/TalkBack, Issue #6), physical devices & zoom reflow (Issue #7), and representative host applications (Issue #8) are verified. Automated axe and emulation do not substitute for continuous human evaluation. 2. **Local Firefox remains unavailable on this Mac.** The complete Firefox browser scenarios passed on Linux, so the local launch issue does not block automated release verification. 3. **License resolved for this release:** on 2026-10-13 the owner confirmed authority to license all included code under ISC. LICENSE and package/lock metadata now agree on ISC. Historical GPL/ISC/MIT discrepancies remain recorded in baseline/migration evidence. 4. **Version 2 identity and channel:** `accessibility-plugin-react@2.0.0` is published under `latest`, superseding the unpublished beta candidate. Registry metadata, integrity, clean React/Next consumers and the browser matrix were verified after npm's publish-time scan completed; see RELEASE.md. @@ -99,7 +111,7 @@ Merged through PR #17 (movement source `d5e21df`), the trigger persists normaliz ## Release tracking -[Project #18](https://github.com/users/prabothcharith/projects/18) and [tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15) track the remaining release work. Owner licensing/identity decisions (#4/#5), documentation correction (#9), final automated candidate checks and npm publication are complete. Human acceptance (#6–#8) and any separately authorized Git tag/GitHub release remain outstanding. +[Project #18](https://github.com/users/prabothcharith/projects/18) and [tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15) track the remaining release work. Owner licensing/identity decisions (#4/#5), documentation correction (#9), final automated candidate checks and npm publication are complete. Human acceptance (#6–#8) is verified and resolved; any separately authorized Git tag/GitHub release remains an owner decision. ## npm identity follow-up diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index b63fdde..101854c 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -36,7 +36,7 @@ No deadlines or percentage-complete estimates. Status is based on current eviden Release gates are not satisfied by checking in tests or CI configuration. Execute them on the final candidate. A local Chromium/WebKit pass is not a Firefox pass, and an axe pass is not screen-reader or WCAG certification. -Release tasks are tracked in [Project #18](https://github.com/users/prabothcharith/projects/18) under [tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15). Documentation status correction (#9) is in PR #17; owner decisions (#4/#5), human acceptance (#6–#8), final candidate validation (#10) and approved publication (#11) remain open gates. +Release tasks are tracked in [Project #18](https://github.com/users/prabothcharith/projects/18) under [tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15). Owner decisions (#4/#5), human acceptance (#6–#8), documentation correction (#9), final candidate validation (#10), and approved publication (#11) are complete. The owner confirmed `accessibility-plugin-react` as the registry identity on 2026-10-13. The npm preparation branch prepares `2.0.0-beta.1`; the owner approved 2.0.0-beta.1 under beta and ISC, and npm maintainer authentication is verified. Stable human acceptance remains pending. See RELEASE.md. From 9b237c4b1365c353ac8c828ab1668e1519a9c6e3 Mon Sep 17 00:00:00 2001 From: praboth charith - GBS - CLI Date: Fri, 20 Nov 2026 15:09:58 +0530 Subject: [PATCH 3/3] docs: reconcile and close release tracker #15 --- docs/BUILD_AND_RELEASE_PLAN.md | 18 +++++++++--------- docs/HANDOVER.md | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) 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.