accessibility-plugin-react 2.18.0 → 2.28.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/NOTICE +24 -0
- package/README.md +48 -26
- package/dist/index.d.mts +1024 -9
- package/dist/index.d.ts +1024 -9
- package/dist/index.js +10034 -3983
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +9232 -3235
- package/dist/index.mjs.map +1 -1
- package/dist/style.css +1749 -0
- package/docs/API.md +195 -23
- package/docs/BUILD_AND_RELEASE_PLAN.md +22 -22
- package/docs/DIAGNOSTICS.md +119 -0
- package/docs/DICTIONARY.md +154 -0
- package/docs/FEATURES.md +93 -31
- package/docs/KEYBOARD_SHORTCUTS.md +97 -0
- package/docs/MENU_CUSTOMIZATION.md +224 -0
- package/docs/PERFORMANCE_PROFILING.md +107 -0
- package/docs/PRIVACY_AND_EVENTS.md +140 -0
- package/docs/PROJECT_STATUS.md +31 -7
- package/docs/PUBLISH_REHEARSAL.md +72 -0
- package/docs/READ_ALOUD.md +55 -0
- package/docs/RELEASE_PROPOSAL_M5.md +100 -0
- package/docs/ROADMAP.md +30 -15
- package/docs/SATURATION_AND_GRAYSCALE.md +74 -0
- package/docs/SECURITY_AUDIT.md +83 -0
- package/docs/SMART_CONTRAST.md +131 -0
- package/docs/SUPPORTED_MATRIX.md +150 -0
- package/docs/TRANSLATION.md +199 -0
- package/docs/VOICE_NAVIGATION.md +124 -0
- package/package.json +2 -1
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Milestone 5 Release Proposal & Semantic Version Recommendation
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-10-28
|
|
4
|
+
**Scope:** Milestone 5 — Launch readiness and package hardening (Issues #66, #67, #68, #69, #70, #71)
|
|
5
|
+
**Parent Trackers:** [Issue #27](https://github.com/prabothcharith/accessibility-plugin-react/issues/27), [Issue #15](https://github.com/prabothcharith/accessibility-plugin-react/issues/15), [Issue #21](https://github.com/prabothcharith/accessibility-plugin-react/issues/21)
|
|
6
|
+
**Current Registry State:** `accessibility-plugin-react@2.28.0` on npm under tag `latest`
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Executive Summary
|
|
11
|
+
|
|
12
|
+
Milestone 5 focused on comprehensive package hardening, multi-browser and device matrix verification, runtime profiling, security and dependency auditing, documentation synchronization, and clean consumer publish rehearsals.
|
|
13
|
+
|
|
14
|
+
All six Milestone 5 sub-issues have completed all functional, programmatic, and integration requirements:
|
|
15
|
+
|
|
16
|
+
- **A11Y-501 (Issue #66):** Full supported-browser, device, and assistive-technology matrix (`docs/SUPPORTED_MATRIX.md`).
|
|
17
|
+
- **A11Y-502 (Issue #67):** Performance, bundle, listener, and leak profiling (`docs/PERFORMANCE_PROFILING.md`).
|
|
18
|
+
- **A11Y-503 (Issue #68):** Documentation website, API reference, and interactive examples (`CONTRIBUTING.md`, `docs/API.md`, `docs/FEATURES.md`, examples).
|
|
19
|
+
- **A11Y-504 (Issue #69):** Dependency, license, CSP, and security audit (`NOTICE`, `docs/SECURITY_AUDIT.md`, `tests/securityAudit.test.ts`).
|
|
20
|
+
- **A11Y-505 (Issue #70):** Packed publish rehearsal and clean consumer smoke testing (`docs/PUBLISH_REHEARSAL.md`).
|
|
21
|
+
- **A11Y-506 (Issue #71):** Version recommendation, changelog, and owner-approved release proposal (this document).
|
|
22
|
+
|
|
23
|
+
This document reviews the complete verification evidence, evaluates semantic versioning options, reconciles legacy release trackers, and provides an owner decision checklist. In accordance with repository governance rules, **no publish, tag, or default-branch merge is performed without explicit owner authorization**.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 2. Milestone 5 Verification Evidence
|
|
28
|
+
|
|
29
|
+
| Issue | Area | Verification Artifacts | Status | Results & Key Metrics |
|
|
30
|
+
| ------------------ | ------------------------ | ------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
31
|
+
| **#66 (A11Y-501)** | Supported Matrix & AT | `docs/SUPPORTED_MATRIX.md`<br>`tests/browser/widget.spec.ts` | **PASS** | • Verified Chromium, Firefox, WebKit, Mobile WebKit, Android emulation.<br>• 400% zoom reflow at 320px CSS viewport width verified without clipping.<br>• Forced-colors protection (`forced-colors: active`) verified.<br>• $\ge 44\text{px} \times 44\text{px}$ touch targets verified across all controls.<br>• Zero universal WCAG claims; automated tests establish semantics, human testing mandatory. |
|
|
32
|
+
| **#67 (A11Y-502)** | Performance & Leaks | `docs/PERFORMANCE_PROFILING.md`<br>`tests/performanceProfiling.test.tsx` | **PASS** | • Distribution bundle: ESM `index.mjs` 603 KB raw / 111 KB gzip; CSS 71 KB raw / 11 KB gzip.<br>• React 18 consumer application bundle: 130 KB gzip.<br>• Closed idle runtime: 0 unthrottled pointer listeners, 0 RAF loops, 0 timers.<br>• 1,000-node DOM scaling: multi-feature application & reset under heavy parallel CPU.<br>• 100 mount/unmount & toggle cycles: 0 leaked DOM nodes, 0 leaked styles, 0 memory drift. |
|
|
33
|
+
| **#68 (A11Y-503)** | Documentation & Examples | `CONTRIBUTING.md`<br>`docs/API.md`<br>`docs/FEATURES.md`<br>`examples/*` | **PASS** | • Added `CONTRIBUTING.md` with PR guidelines, coding conventions, and a11y bounds.<br>• Synchronized `docs/API.md` with complete components table and exported types.<br>• Synchronized `docs/FEATURES.md` with Smart Contrast prototype documentation.<br>• Updated `examples/basic-usage` and `examples/next-app` with all prebuilt controllers. |
|
|
34
|
+
| **#69 (A11Y-504)** | Security & Licenses | `NOTICE`<br>`docs/SECURITY_AUDIT.md`<br>`tests/securityAudit.test.ts` | **PASS** | • 0 runtime dependencies (`dependencies: {}`); 0 `npm audit` vulnerabilities.<br>• Added `NOTICE` attributing ISC license, historical origins, and assets.<br>• Strict CSP compliance: 0 dynamic `eval`, 0 `Function()`, 0 inline script injections.<br>• Strict privacy: 0 network telemetry, 0 analytics, 0 audio/transcript transmission.<br>• Sensitive data protection: automatic credential/password exclusion (`isSensitiveElement`). |
|
|
35
|
+
| **#70 (A11Y-505)** | Publish Rehearsal | `docs/PUBLISH_REHEARSAL.md`<br>`scripts/check-package.mjs` | **PASS** | • Exact tarball `.consumers/package.tgz`: 61 files, 1.18 MB unpacked; includes `NOTICE`.<br>• Clean consumer installations passed in React 18.3.1, React 19.2.0, and Next.js 16.0.0.<br>• Zero SSR hydration mismatches; clean production builds generated across all consumers. |
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 3. Semantic Versioning Analysis & Recommendation
|
|
40
|
+
|
|
41
|
+
### Contract & Scope Evaluation
|
|
42
|
+
|
|
43
|
+
1. **Backwards Compatibility:**
|
|
44
|
+
- All public contracts established in version 2.0.0 remain 100% backwards-compatible.
|
|
45
|
+
- Zero deprecated APIs were removed; zero existing prop types, function signatures, or CSS custom properties were altered in breaking ways.
|
|
46
|
+
- Therefore, a major version bump (`3.0.0`) is **not warranted**.
|
|
47
|
+
|
|
48
|
+
2. **Milestone 5 Additions:**
|
|
49
|
+
- Milestone 5 added legal packaging (`NOTICE` bundled into the npm archive), extensive documentation (`docs/SUPPORTED_MATRIX.md`, `docs/PERFORMANCE_PROFILING.md`, `docs/SECURITY_AUDIT.md`, `docs/PUBLISH_REHEARSAL.md`, `CONTRIBUTING.md`), new regression and profiling test suites (`tests/performanceProfiling.test.tsx`, `tests/securityAudit.test.ts`), and package verification scripts (`scripts/check-package.mjs`).
|
|
50
|
+
- The underlying library runtime code remains identical to the stabilized v2.28.0 release.
|
|
51
|
+
|
|
52
|
+
### Version Recommendation
|
|
53
|
+
|
|
54
|
+
We present two valid options for the owner's authorization:
|
|
55
|
+
|
|
56
|
+
- **Option A (Recommended): Version `2.29.0` (Minor Release)**
|
|
57
|
+
- _Rationale:_ SemVer convention often treats milestone completion and legal attribution additions (`NOTICE` in tarball files) as a minor increment signifying a hardened, launch-ready milestone milestone release. It clearly demarcates the pre-hardening releases (2.28.0 and earlier) from the fully profiled, audited, and matrix-verified release.
|
|
58
|
+
- _Publish target:_ npm tag `latest`.
|
|
59
|
+
|
|
60
|
+
- **Option B: Version `2.28.1` (Patch Release)**
|
|
61
|
+
- _Rationale:_ If the owner strictly interprets SemVer to require new public runtime API functions for a minor bump. Because M5 primarily added packaging metadata (`NOTICE`), documentation, and automated test suites without introducing new end-user React components or hooks beyond those already present in 2.28.0, `2.28.1` accurately reflects a hardening patch.
|
|
62
|
+
- _Publish target:_ npm tag `latest`.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 4. Reconciliation of Legacy Release Trackers
|
|
67
|
+
|
|
68
|
+
### Issue #15 ("First stable release: acceptance and publication tracker")
|
|
69
|
+
|
|
70
|
+
Issue #15 was created early in the repository lifecycle to track the initial stable release sequence. Its child issues are reconciled as follows:
|
|
71
|
+
|
|
72
|
+
1. **Issue #4 (Licensing conflict):** Closed. Owner confirmed ISC for all code; `LICENSE` and `NOTICE` are verified.
|
|
73
|
+
2. **Issue #5 (Package identity):** Closed. Owner selected `accessibility-plugin-react`; published under `latest`.
|
|
74
|
+
3. **Issue #6 (Screen-reader accessibility acceptance):**
|
|
75
|
+
- _Status:_ Programmatic accessibility semantics verified via automated axe-core audits and Playwright tests in `tests/browser/widget.spec.ts`.
|
|
76
|
+
- _Documentation:_ `docs/DEVELOPMENT.md` and `docs/SUPPORTED_MATRIX.md` document detailed manual VoiceOver, NVDA, and TalkBack protocols.
|
|
77
|
+
- _Policy:_ Automated tests do not certify WCAG compliance; continuous human assistive technology testing remains an active operational discipline.
|
|
78
|
+
4. **Issue #7 (Physical devices, actual zoom, visual accessibility):**
|
|
79
|
+
- _Status:_ Verified in automated browser matrix (Mobile WebKit emulation, 320px reflow, 400% zoom reflow, forced-colors mode).
|
|
80
|
+
- _Documentation:_ Manual physical device touch testing protocol documented in `docs/DEVELOPMENT.md`.
|
|
81
|
+
5. **Issue #8 (Representative host-application acceptance):**
|
|
82
|
+
- _Status:_ Verified via packed clean consumer test suite (`npm run test:consumers`) in React 18 (Vite), React 19 (Tailwind), and Next.js 16 (Webpack/App Router/SSR).
|
|
83
|
+
6. **Issue #9 (Documentation update):** Closed. All documentation synchronized.
|
|
84
|
+
7. **Issue #10 (Final release candidate validation):** Fulfilled by Issue #70 (A11Y-505) and `docs/PUBLISH_REHEARSAL.md`.
|
|
85
|
+
8. **Issue #11 (Publish approved package):** Automated via GitHub Actions npm OIDC trusted publishing in `.github/workflows/publish.yml`.
|
|
86
|
+
|
|
87
|
+
### Milestone 5 Tracker (Issue #27)
|
|
88
|
+
|
|
89
|
+
With the completion of Issue #71, all child issues of Milestone 5 (#66, #67, #68, #69, #70, #71) are complete. Issue #27 may now be closed upon owner approval of this proposal.
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 5. Owner Decision Checklist
|
|
94
|
+
|
|
95
|
+
The repository owner authorized release on 2026-10-28:
|
|
96
|
+
|
|
97
|
+
- [x] **1. Release Version Choice:** Option B (`2.28.1` patch release) confirmed by owner.
|
|
98
|
+
- [x] **2. Default Branch Merge:** Authorized merge of release branch into `development` and synchronization into `main`.
|
|
99
|
+
- [x] **3. Publication Authorization:** Automated GitHub Actions npm trusted publishing (`publish.yml`) via OIDC and GitHub Packages (`publish-github-package.yml`) triggered upon merge to `main`.
|
|
100
|
+
- [x] **4. Git Release Tag:** Create matching `v2.28.1` Git tag and release upon verified npm registry upload.
|
package/docs/ROADMAP.md
CHANGED
|
@@ -2,21 +2,36 @@
|
|
|
2
2
|
|
|
3
3
|
No deadlines or percentage-complete estimates. Status is based on current evidence in PROJECT_STATUS.md.
|
|
4
4
|
|
|
5
|
-
| Phase
|
|
6
|
-
|
|
|
7
|
-
| Investigation
|
|
8
|
-
| Core stabilization
|
|
9
|
-
| Features and extension
|
|
10
|
-
| Accessibility/UI
|
|
11
|
-
| Packaging/frameworks
|
|
12
|
-
| CI/release validation
|
|
13
|
-
| Clean light base design
|
|
14
|
-
| Movement and quick actions
|
|
15
|
-
| Ownership/release
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
|
|
|
5
|
+
| Phase | Priority | Objective / tasks | Dependencies | Acceptance / deliverables | Risk / status |
|
|
6
|
+
| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
7
|
+
| Investigation | P0 | Compare vanilla/main/development/new-development, PR #1, history; baseline all checks | Git/registry access | Evidence-backed baseline and parity matrix | Completed locally |
|
|
8
|
+
| Core stabilization | P0 | Provider effects, filter composition, independent storage, reset cancellation, no invisible hit area | Baseline | Close/reopen, reset race, restore, dynamic content and cleanup regressions | Implemented; local automated verification |
|
|
9
|
+
| Features and extension | P1 | All fifteen controllers, missing original variants, safe custom apply contract | Core | Per-feature bounds/states and custom restore/reset/unmount tests; public examples | Implemented; host-specific effect limits documented |
|
|
10
|
+
| Accessibility/UI | P1 | Non-modal semantics, names/focus, safe-area responsive CSS, motion preferences | Core | Keyboard/browser/axe checks plus human SR, actual zoom and device review | Automated checks implemented; human review remains |
|
|
11
|
+
| Packaging/frameworks | P1 | Client boundary, ESM/CJS/types/CSS, React 18/19, Next App/Pages, built examples | Core + build | Clean tarball installs, production builds and runtime tests | Local and hosted consumer verification passed; complete Firefox coverage passed on Linux |
|
|
12
|
+
| CI/release validation | P1 | Execute hosted matrix; fix Firefox launch environment; record results | Push/PR workflow and compatible runner | Passing Node22/24 jobs and full browser matrix on exact release commit | Completed: hosted Node22/24 and full Chromium/Firefox/WebKit/mobile matrix passed |
|
|
13
|
+
| Clean light base design | P1 | Apply owner-selected light concept, icons, tokens and responsive rows | Stabilized core | Browser/axe/target-size checks, actual runtime screenshots and documented overrides | Merged through PR #16; local and hosted checks passed |
|
|
14
|
+
| Movement and quick actions | P1 | Persist drag/corner placement, non-drag controls and fixed reset/footer | Clean light foundation | Drag/cancel/reload/resize and pinned-action browser regressions | Merged through PR #17; local and full hosted checks passed |
|
|
15
|
+
| Ownership/release | P1 | Continue confirmed npm identity; resolve license; choose version; approve merge/tag/publish | Owner decision + all gates | Traceable authorized release with clean registry install | 2.0.0/latest published; automated release pipeline active for 2.1.0–2.22.0 |
|
|
16
|
+
| Modular control primitives | P1 | Accessible primitives (Toggle, Choice, Stepper, Card, Preview), search counts, empty/error UI states | Clean light core | WCAG 2.2 touch target, radiogroup/switch keyboard semantics, live announcements | Completed; released in v2.3.0 |
|
|
17
|
+
| Typography enhancements | P1 | TextScale (stepwise), LineHeight presets, script-aware LetterSpacing and WordSpacing, ParagraphSpacing | Core text engine | Arabic cursive protection, Sinhala/Tamil script bounds, reflow safety | Completed; released in v2.4.0–v2.9.0 |
|
|
18
|
+
| Reading aids & Media hiding | P1 | ReadingGuide, ReadingMask, BigCursor fine-pointer detection, HideDecorativeImages, HideVideos | Portal layout | Safe-area fit, pointer-transparency, alt text preservation, performance | Completed; released in v2.10.0–v2.14.0 |
|
|
19
|
+
| Navigation, Presets & I18n | P1 | PageNavigator, Tooltips (WCAG 1.4.13), Profiles, Custom Presets JSON transfer, ReadingMode, Shortcuts | Core store & i18n | Heading tree, focus restoration, zero tracking, Sinhala/Tamil localizations | Completed; released in v2.15.0–v2.19.0 |
|
|
20
|
+
| Native Speech TTS (Issue 57) | P1 | User-initiated Web Speech read-aloud with sentence chunking, pitch/rate, voice selector, floating bar | Web Speech API | Zero network calls, sensitive field exclusions, no auto-play | Completed; released in v2.20.0 |
|
|
21
|
+
| Saturation/Grayscale (58) | P1 | Opt-in saturation levels, monochrome grayscale, image/chart advisory warnings, forced-colors bypass | Filter pipeline | Non-destructive reset, high-contrast OS detection, accessible advisories | Completed; released in v2.21.0 |
|
|
22
|
+
| Menu Customization (Issue 60) | P1 | Per-site feature menu reordering, grouping, custom labels, safe diagnostics, and stable rerenders | AccessibilityList / FeatureMenu | Non-crashing error handling, preserved canonical IDs, memoized focus stability | Completed; released in v2.23.0 |
|
|
23
|
+
| Diagnostics & Harness (61) | P1 | Dev-only integration diagnostics, containing-block traps, CSP, host CSS, DOM landmarks and test harness | Diagnostics engine & harness | Zero compliance claims, strict privacy guarantees, actionable fixes | Completed; released in v2.24.0 |
|
|
24
|
+
| Smart Contrast Prototype (63) | P1 | Measured smart contrast for eligible elements with compositing, caching, unsupported reporting, full restore | Smart contrast engine & controller | Non-destructive restoration, no layout thrashing, Porter-Duff compositing, zero claims | Completed; released in v2.26.0 |
|
|
25
|
+
| Voice Navigation Prototype (64) | P1 | Client-side voice navigation for headings and scrolling with timeout, tab cleanup, zero recording storage | Web Speech Recognition & controller | Inactivity timeout, document.hidden protection, zero audio storage, keyboard fallbacks | Completed; released in v2.27.0 |
|
|
26
|
+
| Host Translation Adapter (65) | P1 | Decoupled translation provider interface, consent modal, sensitive field exclusion, DOM restoration | Translation engine & controller | Explicit consent, privacy threat model, zero default requests, textContent sanitization | Completed; released in v2.28.0 |
|
|
27
|
+
| Compatibility Matrix (Issue 66) | P1 | Full supported-browser, device, zoom reflow, forced-colors, safe-area and touch-target matrix | Test suite & documentation | 320px 400% reflow, forced-colors bypass, 44px targets, zero overclaims | Completed; documented in docs/SUPPORTED_MATRIX.md |
|
|
28
|
+
| Performance Profiling (Issue 67) | P1 | Measure bundle gzip, closed runtime, 1,000-node DOM jank, 100 mount/unmount and toggle cycles | Performance test suite & doc | Actual gzip/brotli metrics, <45ms main thread, 0 leaks, 0 compounding | Completed; documented in docs/PERFORMANCE_PROFILING.md |
|
|
29
|
+
| Documentation & Demos (Issue 68) | P1 | Synchronize README, API, FEATURES, CONTRIBUTING, and runnable Vite/Next consumer examples | Documentation and examples | Complete API & features sync, CONTRIBUTING guide, full runnable package demos | Completed; documented in CONTRIBUTING.md, docs/API.md, docs/FEATURES.md |
|
|
30
|
+
| Security & Audit (Issue 69) | P1 | Audit dependencies, licenses, NOTICE, CSP, unsafe eval/HTML, privacy model, and vulnerabilities | Security & audit test suite | 0 dependencies, 0 audit advisories, strict CSP compliance, sensitive data protection | Completed; documented in NOTICE, docs/SECURITY_AUDIT.md |
|
|
31
|
+
| Publish Rehearsal (Issue 70) | P1 | Pack dry-run archive inspection, clean React 18/19 and Next.js 16 consumer builds and SSR verification | Consumer validation scripts | Tarball inspection passed, clean React 18/19/Next installs and production builds passed | Completed; documented in docs/PUBLISH_REHEARSAL.md |
|
|
32
|
+
| Release Proposal (Issue 71) | P1 | Review evidence, recommend patch/minor, prepare dated changelog, reconcile #15, and await owner approval | Release proposal & versioning analysis | Comprehensive evidence review, SemVer recommendation, legacy tracker reconciliation | Completed; documented in docs/RELEASE_PROPOSAL_M5.md |
|
|
33
|
+
| Host effects hardening | P2 | Optional explicit effect scopes, CSP renderer, Shadow DOM strategy, fixed-descendant filter alternatives | API design and real use cases | Documented contract with package/browser tests | Planned; avoid universal-host compatibility claims |
|
|
34
|
+
| Multi-instance/cross-tab | P2 | Decide if needed; deterministic arbitration/synchronization | Usage evidence | Isolated lifetime, persistence and interaction tests | Deferred; one provider/document enforced |
|
|
20
35
|
|
|
21
36
|
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.
|
|
22
37
|
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Saturation and Grayscale Modes (A11Y-402)
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The `accessibility-plugin-react` library provides opt-in, non-destructive color saturation and monochrome grayscale display modes via `SaturationController` and `GrayscaleController`.
|
|
6
|
+
|
|
7
|
+
These modes allow users with photophobia, visual fatigue, migraine susceptibility, color processing differences, or cognitive processing needs to adjust color intensity without breaking host styles, causing compounding filters, or leaking stale styles across client-side navigation.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Capabilities & Modes
|
|
12
|
+
|
|
13
|
+
| Mode | Value | Applied CSS Filter | Use Case |
|
|
14
|
+
| ------------------- | ------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| **Original / Off** | `0` or `"original"` | None (`""`) | Default natural site colors. |
|
|
16
|
+
| **Low Saturation** | `1` or `"low"` | `saturate(0.2)` | Reduces color chroma by 80% to alleviate visual overstimulation and sensory overload while retaining faint chromatic cues. |
|
|
17
|
+
| **High Saturation** | `2` or `"high"` | `saturate(2)` | Increases color chroma by 200% for users with low contrast sensitivity who need vivid distinctions between colors. |
|
|
18
|
+
| **Grayscale** | `3` or `"grayscale"` (or `grayscale: true`) | `grayscale(1)` | Full monochrome mode eliminating all color hues for users with severe photophobia or specific color processing conditions. |
|
|
19
|
+
|
|
20
|
+
Both controllers can be used independently or composed together:
|
|
21
|
+
|
|
22
|
+
- `SaturationController` offers segmented buttons (`Off`, `Low`, `High`, `Grayscale`) with an optional `includeGrayscale={false}` flag if developers prefer rendering `GrayscaleController` separately.
|
|
23
|
+
- `GrayscaleController` offers an accessible standalone toggle switch button.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Documented Chart and Image Risks
|
|
28
|
+
|
|
29
|
+
When modifying color saturation or applying grayscale, users face specific perceptual trade-offs that web authors and users must understand:
|
|
30
|
+
|
|
31
|
+
### 1. Data Visualizations, Charts, and Maps (WCAG 1.4.1 Use of Color)
|
|
32
|
+
|
|
33
|
+
- **The Risk**: Charts, line graphs, pie charts, topological maps, and transit diagrams that convey meaning _solely through color hue_ (e.g., green for positive, red for negative, multi-colored lines for series) lose distinction when saturation is reduced or grayscale is applied.
|
|
34
|
+
- **Mitigation & Advisory**: Both controllers display a polite, visible advisory notice (`role="note"`, `aria-live="polite"`):
|
|
35
|
+
- _Low Saturation_: `"Low saturation reduces color differences. Color-coded charts and indicators may be harder to distinguish."*
|
|
36
|
+
- _Grayscale_: `"Grayscale removes all color. Visualizations and charts relying on color alone may require alternative labels."*
|
|
37
|
+
- **Author Best Practice**: Ensure all charts use distinct stroke dash patterns, hatch fills, direct text callouts, or data table alternatives so they remain comprehensible in monochrome.
|
|
38
|
+
|
|
39
|
+
### 2. High Saturation Glare and Image Clipping
|
|
40
|
+
|
|
41
|
+
- **The Risk**: Scaling saturation to 200% (`saturate(2)`) causes highly saturated reds, magentas, and cyans to clip to the gamut boundary (`#ff0000`, `#ff00ff`), causing halo artifacts around high-contrast edges and visual glare.
|
|
42
|
+
- **Mitigation & Advisory**:
|
|
43
|
+
- _High Saturation_: `"High saturation increases color intensity (200%), which may cause visual glare or color clipping."*
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Forced-Colors (High Contrast) Protection
|
|
48
|
+
|
|
49
|
+
When an operating system forced-colors mode (such as Windows High Contrast Mode) is active, browser media query `@media (forced-colors: active)` indicates that the OS is enforcing an authoritative high-contrast palette.
|
|
50
|
+
|
|
51
|
+
1. **Automatic Filter Bypass**: `composeFilter()` detects `isForcedColorsActive()` and immediately returns an empty filter string `""`. This prevents CSS `saturate()` or `grayscale()` from interfering with the system's high-contrast color scheme.
|
|
52
|
+
2. **Accessible Notice**: Both controllers monitor forced-colors status using `useSyncExternalStore(subscribeForcedColors, isForcedColorsActive)` and render a clear status message:
|
|
53
|
+
`"Operating system high contrast (forced colors) is active. Filter effects are bypassed to preserve OS contrast."`
|
|
54
|
+
3. **Preference Retention**: The user's chosen saturation level remains preserved in preferences and will take effect if forced-colors mode is subsequently disabled.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Instant Reversible Reset Across Chromium, Firefox, and WebKit
|
|
59
|
+
|
|
60
|
+
Color filters are applied to top-level host body children rather than `<html>` or `<body>` to prevent creating unexpected CSS containing blocks that would distort fixed widget placement and portal elements:
|
|
61
|
+
|
|
62
|
+
1. **Reversible Mutations**: The scoped effect engine tracks prior inline values and priorities (`element.style.getPropertyValue("filter")`).
|
|
63
|
+
2. **Instant Reset**: When Reset All executes or when a user clicks "Off", the cleanup function restores the element's exact prior inline styles or calls `element.style.removeProperty("filter")`.
|
|
64
|
+
3. **No Stale Filter Leakage**: Tested across Chromium, Firefox, and WebKit to guarantee `getComputedStyle(element).filter` returns `"none"` after reset, with zero residual stacking contexts or color distortion.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Localization Support
|
|
69
|
+
|
|
70
|
+
All labels, segment titles, and advisory warnings are fully localized in:
|
|
71
|
+
|
|
72
|
+
- English (`en`, `en-US`, `en-GB`)
|
|
73
|
+
- Sinhala (`si`, `si-LK`): e.g., `සන්තෘප්තිය`, `අක්රියයි`, `අඩු`, `ඉහළ`, `අළු පැහැ`
|
|
74
|
+
- Tamil (`ta`, `ta-LK`): e.g., `நிறச்செறிவூட்டல்`, `முடக்கு`, `குறைந்த`, `அதிக`, `சாம்பல் நிறம்`
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Security, dependency, license and privacy audit (A11Y-504)
|
|
2
|
+
|
|
3
|
+
This document provides a comprehensive security review, dependency audit, Content Security Policy (CSP) compliance analysis, privacy threat model, and intellectual property/licensing verification for `accessibility-plugin-react`.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Executive summary and audit results
|
|
8
|
+
|
|
9
|
+
| Audit Area | Standard / Requirement | Current Verification Result | Status |
|
|
10
|
+
| :------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------- |
|
|
11
|
+
| **Dependencies** | 0 runtime dependencies; peerDependencies only | Clean `package.json`; 0 runtime dependencies. Only peer dependencies: React (`^18.3.1 \|\| ^19.0.0`) and React DOM. | **PASS** |
|
|
12
|
+
| **Vulnerabilities** | `npm audit` 0 findings across direct and transitive tooling | `npm audit` returns 0 vulnerabilities across all installed packages. | **PASS** |
|
|
13
|
+
| **Script Injection** | No dynamic code execution (`eval`, `new Function`) | Automated AST scan verifies 0 instances of `eval` or `Function` constructors across all `src/` modules. | **PASS** |
|
|
14
|
+
| **Network Requests** | No unauthorized telemetry, tracking, or background calls | 0 `fetch()`, 0 `XMLHttpRequest`, 0 `navigator.sendBeacon`, 0 `WebSocket` calls. | **PASS** |
|
|
15
|
+
| **Data Residency** | All state stored locally; zero external exfiltration | Preferences persist strictly in `localStorage` under `react-accessibility-plugin:state`. Zero cloud sync. | **PASS** |
|
|
16
|
+
| **Licensing** | Permissive ISC license; clean IP attribution | Dedicated `LICENSE` and `NOTICE` files committed; zero GPL/copyleft or proprietary binary assets. | **PASS** |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 2. Content Security Policy (CSP) compliance
|
|
21
|
+
|
|
22
|
+
The library is designed to function cleanly under strict corporate and enterprise Content Security Policies:
|
|
23
|
+
|
|
24
|
+
### Script Execution (`script-src`)
|
|
25
|
+
|
|
26
|
+
- **No Unsafe Eval**: The library never invokes `eval()` or constructs functions from strings. It is 100% compatible with CSPs that omit `'unsafe-eval'`.
|
|
27
|
+
- **Pre-Compiled Distributions**: Ships standard pre-bundled ESM and CommonJS artifacts; no runtime transpilation or script loaders are used.
|
|
28
|
+
|
|
29
|
+
### Style Sheets & Styling (`style-src`)
|
|
30
|
+
|
|
31
|
+
- **Scoped Plain CSS**: The library injects its stylesheet (`.arap-*`) scoped to its own container and uses CSS custom properties (`--arap-*`) on `.arap-root` and `.arap-panel`.
|
|
32
|
+
- **Standalone Stylesheet Option**: Applications with CSPs that disallow inline styles (`'unsafe-inline'`) can load the standalone pre-compiled stylesheet directly:
|
|
33
|
+
```css
|
|
34
|
+
@import "accessibility-plugin-react/style.css";
|
|
35
|
+
```
|
|
36
|
+
See [docs/CSP.md](CSP.md) for detailed nonce and hash configuration guidance.
|
|
37
|
+
|
|
38
|
+
### URL Protocol Sanitization (`isSafeUrl`)
|
|
39
|
+
|
|
40
|
+
- When displaying links in reading mode or page navigation, all URLs undergo strict protocol verification (`isSafeUrl()`):
|
|
41
|
+
- Permitted protocols: `http:`, `https:`, relative paths (`/`, `./`, `../`), in-page hashes (`#`), and safe `data:image/` URLs.
|
|
42
|
+
- Prohibited schemes: `javascript:`, `vbscript:`, and unknown protocols are immediately rejected to prevent cross-site scripting (XSS) vectors.
|
|
43
|
+
|
|
44
|
+
### DOM Updates & XSS Safeguards
|
|
45
|
+
|
|
46
|
+
- **TextContent Assignment**: The host translation adapter assigns translated content exclusively through `Text.textContent`, never `innerHTML`, completely eliminating script injection vectors.
|
|
47
|
+
- **Reading Mode HTML Sanitization**: Strips executable elements (`<script>`, `<iframe>`, `<object>`, `<embed>`) and inline event handlers (`onload`, `onclick`, `onerror`).
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. Privacy threat model and data residency
|
|
52
|
+
|
|
53
|
+
### Zero Telemetry & Tracking
|
|
54
|
+
|
|
55
|
+
- The library does not contain analytics beacons, tracking pixels, cookie setters, or telemetry endpoints.
|
|
56
|
+
- No network requests are made during normal widget lifecycle or feature toggling.
|
|
57
|
+
|
|
58
|
+
### Sensitive Element Detection (`isSensitiveElement`)
|
|
59
|
+
|
|
60
|
+
Features that inspect or transform DOM elements (such as host translation, read aloud, and smart contrast) automatically exclude sensitive and private nodes:
|
|
61
|
+
|
|
62
|
+
- **Credentials & Passwords**: `input[type="password"]`, `input[type="hidden"]`.
|
|
63
|
+
- **Financial Data**: `[autocomplete*="password"]`, `[autocomplete*="cc-"]`, `[autocomplete*="credit-card"]`.
|
|
64
|
+
- **Code & Technical Content**: `<code>`, `<pre>`, `<kbd>`, `<samp>`, `<script>`, `<style>`.
|
|
65
|
+
- **Explicit Opt-Out Tags**: `[translate="no"]`, `.notranslate`, `[data-no-translate]`, `[data-sensitive]`.
|
|
66
|
+
- **Cross-Origin Boundaries**: `<iframe>` elements are strictly skipped to prevent Same-Origin Policy (SOP) bypass.
|
|
67
|
+
|
|
68
|
+
### Client-Side Speech & Microphone Privacy
|
|
69
|
+
|
|
70
|
+
- **Web Speech API**: Text-to-speech synthesis and voice navigation utilize native browser platform engines (`window.speechSynthesis`, `window.SpeechRecognition`).
|
|
71
|
+
- **Zero Audio Retention**: No microphone recordings or voice audio streams are ever stored in `localStorage`, `sessionStorage`, or transmitted to remote servers.
|
|
72
|
+
- **Inactivity Watchdog**: Voice listening terminates automatically after 30 seconds of inactivity or when the tab becomes hidden (`document.hidden`).
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 4. License and intellectual property audit
|
|
77
|
+
|
|
78
|
+
- **License**: Released under the open-source **ISC License** (permissive, GPL-compatible).
|
|
79
|
+
- **Attribution**: Derived from the original vanilla JavaScript accessibility plugin; attribution is documented in `NOTICE` and `README.md`.
|
|
80
|
+
- **Assets**:
|
|
81
|
+
- **Fonts**: No binary font files (`.woff`, `.woff2`, `.ttf`) are bundled. Presets rely entirely on standard system font stacks.
|
|
82
|
+
- **Icons**: Authored in-tree as native inline SVG icons under ISC.
|
|
83
|
+
- **Glossary Data**: Built-in dictionary entries (English, Sinhala, Tamil) are compiled in-tree under ISC for offline accessibility lookup.
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# Smart Contrast Research Prototype (A11Y-407)
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The Smart Contrast Research Prototype provides opt-in, measured contrast assistance for eligible visible elements on the host page. It measures foreground text colors against computed backdrops using WCAG 2.1 relative luminance mathematics, enhances low-contrast elements via batched non-destructive style mutations, and identifies complex or unsupported elements (such as CSS gradients, background images, and backdrop filters).
|
|
6
|
+
|
|
7
|
+
> [!WARNING]
|
|
8
|
+
> **Zero Automatic WCAG Compliance Claim**:
|
|
9
|
+
> Smart contrast is strictly an opt-in research prototype. Mathematical luminance calculations on computed styles do not constitute or certify legal, regulatory, or formal WCAG 2.1 AA/AAA compliance. Visual verification, contextual human review, and manual accessibility audits remain mandatory.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Mathematical Specification
|
|
14
|
+
|
|
15
|
+
Smart contrast implements the standard W3C WCAG 2.1 relative luminance and contrast ratio algorithms.
|
|
16
|
+
|
|
17
|
+
### 1. sRGB Linearization
|
|
18
|
+
|
|
19
|
+
Each 8-bit color component ($R, G, B \in [0, 255]$) is converted to an sRGB floating-point value $c = C / 255$ and linearized:
|
|
20
|
+
|
|
21
|
+
$$
|
|
22
|
+
c_{linear} = \begin{cases}
|
|
23
|
+
\frac{c}{12.92} & \text{if } c \le 0.04045 \\
|
|
24
|
+
\left(\frac{c + 0.055}{1.055}\right)^{2.4} & \text{if } c > 0.04045
|
|
25
|
+
\end{cases}
|
|
26
|
+
$$
|
|
27
|
+
|
|
28
|
+
### 2. Relative Luminance ($L$)
|
|
29
|
+
|
|
30
|
+
Linearized components are weighted by human spectral sensitivity coefficients:
|
|
31
|
+
|
|
32
|
+
$$
|
|
33
|
+
L = 0.2126 \cdot R_{linear} + 0.7152 \cdot G_{linear} + 0.0722 \cdot B_{linear}
|
|
34
|
+
$$
|
|
35
|
+
|
|
36
|
+
Relative luminance ranges from $0.0$ (pure black `#000000`) to $1.0$ (pure white `#ffffff`).
|
|
37
|
+
|
|
38
|
+
### 3. Contrast Ratio ($CR$)
|
|
39
|
+
|
|
40
|
+
Given relative luminances $L_1$ and $L_2$:
|
|
41
|
+
|
|
42
|
+
$$
|
|
43
|
+
CR = \frac{\max(L_1, L_2) + 0.05}{\min(L_1, L_2) + 0.05}
|
|
44
|
+
$$
|
|
45
|
+
|
|
46
|
+
The resulting ratio is between $1.0:1$ (identical colors) and $21.0:1$ (pure black on pure white).
|
|
47
|
+
|
|
48
|
+
### 4. WCAG 2.1 Thresholds
|
|
49
|
+
|
|
50
|
+
- **Level AA (SC 1.4.3)**:
|
|
51
|
+
- Normal text (< 24px, or < 18.66px if bold): $\ge 4.5:1$
|
|
52
|
+
- Large text ($\ge 24px$, or $\ge 18.66px$ with font-weight $\ge 700$): $\ge 3.0:1$
|
|
53
|
+
- **Level AAA (SC 1.4.6)**:
|
|
54
|
+
- Normal text: $\ge 7.0:1$
|
|
55
|
+
- Large text: $\ge 4.5:1$
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Backdrop Compositing & Alpha Blending
|
|
60
|
+
|
|
61
|
+
Web pages frequently use transparent or semi-transparent backgrounds on content cards, tables, badges, and modals. Smart contrast resolves the true effective background beneath each text glyph by traversing the DOM tree upward to `document.body` and `document.documentElement`:
|
|
62
|
+
|
|
63
|
+
1. **Alpha Compositing**: Layers are composited using standard Porter-Duff source-over blending:
|
|
64
|
+
$$
|
|
65
|
+
\alpha_{out} = \alpha_{fg} + \alpha_{bg} \cdot (1 - \alpha_{fg})
|
|
66
|
+
$$
|
|
67
|
+
$$
|
|
68
|
+
C_{out} = \frac{C_{fg} \cdot \alpha_{fg} + C_{bg} \cdot \alpha_{bg} \cdot (1 - \alpha_{fg})}{\alpha_{out}}
|
|
69
|
+
$$
|
|
70
|
+
2. **Early Termination**: When an opaque ancestor background is encountered ($\alpha_{out} = 1.0$), traversal terminates immediately.
|
|
71
|
+
3. **Canvas Fallback**: If the document root is reached with residual transparency, it is blended over pure white (`#ffffff`).
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Layout Thrashing Prevention (Batching Evidence)
|
|
76
|
+
|
|
77
|
+
Interleaving `getComputedStyle()` (DOM reads) with `element.style.setProperty()` (DOM writes) in a loop causes forced synchronous layouts and layout thrashing, severely degrading 60fps frame rates.
|
|
78
|
+
|
|
79
|
+
Smart contrast strictly isolates execution into three sequential phases:
|
|
80
|
+
|
|
81
|
+
```mermaid
|
|
82
|
+
graph LR
|
|
83
|
+
Phase1["Phase 1: Batched Reads<br/>(Reads computed styles, zero writes)"] --> Phase2["Phase 2: Pure Computation<br/>(Luminance, alpha blending, caching)"]
|
|
84
|
+
Phase2 --> Phase3["Phase 3: Batched Writes<br/>(Applies styles, zero reads)"]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
1. **Phase 1 (Batched Reads)**: Reads `computed.color`, `computed.backgroundColor`, `computed.fontSize`, `computed.fontWeight`, `computed.backgroundImage`, and `computed.backdropFilter` for all eligible nodes upfront into memory. Zero DOM mutations occur during this phase.
|
|
88
|
+
2. **Phase 2 (Pure Math & Compositing)**: Evaluates luminance, blends semi-transparent backdrops, parses colors with an in-memory memoization cache, and computes target replacement tokens. Zero DOM reads or writes occur during this phase.
|
|
89
|
+
3. **Phase 3 (Batched Writes)**: Mutates only the elements that fail target thresholds in a single write pass, simultaneously recording original styles in a restoration ledger.
|
|
90
|
+
|
|
91
|
+
### Performance Evidence
|
|
92
|
+
|
|
93
|
+
On a 1,000-node DOM fixture, full evaluation and batched application consistently completes in under **10ms**, well within the 16.6ms budget for a single 60fps animation frame.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Unsupported Elements & Protections
|
|
98
|
+
|
|
99
|
+
Smart contrast refuses to make inaccurate assumptions when the backdrop cannot be measured deterministically:
|
|
100
|
+
|
|
101
|
+
| Unsupported Condition | Detection Mechanism | Handling |
|
|
102
|
+
| :--------------------- | :------------------------------------------------------------- | :--------------------------------------------------------- |
|
|
103
|
+
| **CSS Gradients** | `linear-gradient`, `radial-gradient`, `conic-gradient` | Skipped; flagged in audit as `reason: "gradient"`. |
|
|
104
|
+
| **Background Images** | `backgroundImage` containing `url(...)` | Skipped; flagged in audit as `reason: "background-image"`. |
|
|
105
|
+
| **Backdrop Filters** | `backdrop-filter` or `-webkit-backdrop-filter` | Skipped; flagged in audit as `reason: "backdrop-filter"`. |
|
|
106
|
+
| **Hidden Elements** | `display: none`, `visibility: hidden`, `opacity: 0` | Ignored during candidate discovery. |
|
|
107
|
+
| **Interactive States** | `:disabled`, `[aria-disabled="true"]`, `[aria-invalid="true"]` | Protected; original host semantics preserved. |
|
|
108
|
+
| **Plugin UI** | `[data-arap-ui]`, `.arap-root`, `[data-arap-ignore]` | Strictly excluded from inspection and modification. |
|
|
109
|
+
|
|
110
|
+
The controller exposes an inspectable **Unsupported elements** list showing each skipped element's tag, ID, class, text snippet, and rejection reason.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Non-Destructive Restoration
|
|
115
|
+
|
|
116
|
+
Every modification applied by smart contrast is recorded in an undo stack:
|
|
117
|
+
|
|
118
|
+
- Original `style.color` and its CSS priority (`""` vs `"important"`) are saved.
|
|
119
|
+
- `undo()` cleanly restores original styles or removes the property completely.
|
|
120
|
+
- `data-arap-smart-contrast="true"` tracking attribute is stripped.
|
|
121
|
+
- Calling `undo()` multiple times is strictly idempotent and safe.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Owner Promotion Decision Framework
|
|
126
|
+
|
|
127
|
+
Smart contrast is intentionally designated as a **Research Prototype** (`Prototype` pill displayed in UI) pending formal owner promotion:
|
|
128
|
+
|
|
129
|
+
1. **Host Complexity**: Complex single-page apps with high-frequency canvas/WebGL, animated CSS gradients, or dynamic video backdrops cannot be evaluated with static DOM tree climbing.
|
|
130
|
+
2. **Browser Color Spaces**: Modern display-P3, OKLCH, and color-mix() specifications require expanded color gamut parsing before universal promotion.
|
|
131
|
+
3. **User Agency**: Automated contrast overrides may alter intentional branding or artistic color palettes; users must retain explicit control to toggle between original, AA, and AAA assistance.
|