Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/BUILD_AND_RELEASE_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/HANDOVER.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
30 changes: 26 additions & 4 deletions docs/PROJECT_STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reconcile the accessibility status rows

This marks human evaluation as ongoing rather than pending, but the same status table still labels physical devices and assistive technologies “unverified” and says stable human acceptance is blocked and pending. That conflicts with the new completion records, leaving readers unable to tell whether issues #6–#8 are closed release gates. Update the status rows to match the verified results.

AGENTS.md reference: AGENTS.md:L13-L13

Useful? React with 👍 / 👎.

| 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 |
Expand Down Expand Up @@ -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 `<button type="button">` with dynamic `aria-expanded="true|false"`, `aria-controls`, and visually-hidden `aria-describedby` (`.arap-sr-only`, without HTML `hidden` display:none suppression) announcing drag/keyboard help. The non-modal panel exposes `role="region"` and `aria-label="Accessibility settings"`.
- **Live Status Announcements:** Polite live region (`role="status"`, `aria-live="polite"`, `aria-atomic="true"`) reliably announces button repositioning coordinates and corner placement.
- **Grouped & Segmented Controls:** Radiogroups use `role="radiogroup"` with native arrow key selection; toggles expose `role="switch"` with `aria-checked`; steppers announce discrete numeric percentages and bounded states.
- **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.
Expand All @@ -89,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

Expand Down
Loading