accessibility-plugin-react 2.17.0 → 2.28.0
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/README.md +43 -26
- package/dist/index.d.mts +1093 -9
- package/dist/index.d.ts +1093 -9
- package/dist/index.js +9259 -2570
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +9255 -2618
- package/dist/index.mjs.map +1 -1
- package/dist/style.css +2058 -0
- package/docs/API.md +193 -23
- package/docs/BUILD_AND_RELEASE_PLAN.md +17 -17
- package/docs/DIAGNOSTICS.md +119 -0
- package/docs/DICTIONARY.md +154 -0
- package/docs/FEATURES.md +83 -30
- package/docs/KEYBOARD_SHORTCUTS.md +97 -0
- package/docs/MENU_CUSTOMIZATION.md +224 -0
- package/docs/PRIVACY_AND_EVENTS.md +140 -0
- package/docs/PROJECT_STATUS.md +22 -6
- package/docs/READING_MODE.md +128 -0
- package/docs/READ_ALOUD.md +55 -0
- package/docs/ROADMAP.md +25 -15
- package/docs/SATURATION_AND_GRAYSCALE.md +74 -0
- package/docs/SMART_CONTRAST.md +131 -0
- package/docs/TRANSLATION.md +199 -0
- package/docs/VOICE_NAVIGATION.md +124 -0
- package/package.json +1 -1
package/docs/ROADMAP.md
CHANGED
|
@@ -2,21 +2,31 @@
|
|
|
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; preparing v2.28.0 |
|
|
27
|
+
| Performance/dynamic styling | P2 | Benchmark large documents; incremental observation; attribute/font-load refresh | Real host profiles | Measured budgets, no redundant work, style-change regression tests | Planned; current child-list/resize path works |
|
|
28
|
+
| 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 |
|
|
29
|
+
| 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
30
|
|
|
21
31
|
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
32
|
|
|
@@ -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,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.
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# Host-Content Translation Adapter Architecture
|
|
2
|
+
|
|
3
|
+
Host-content translation architecture, privacy threat model, and DOM restoration for `accessibility-plugin-react`.
|
|
4
|
+
|
|
5
|
+
## Overview & Scope Boundary
|
|
6
|
+
|
|
7
|
+
The host-content translation adapter (**A11Y-409**) provides a decoupled, privacy-safe interface for translating arbitrary host application text.
|
|
8
|
+
|
|
9
|
+
### Strict Distinction from Widget Localization
|
|
10
|
+
|
|
11
|
+
| Dimension | Widget UI Localization (`docs/LOCALES.md`) | Host-Content Translation (`docs/TRANSLATION.md`) |
|
|
12
|
+
| :------------------- | :---------------------------------------------- | :----------------------------------------------------- |
|
|
13
|
+
| **Target Scope** | Widget buttons, labels, and dialog strings only | Arbitrary host document content (articles, headings) |
|
|
14
|
+
| **Network Requests** | **Zero** — 100% static bundled locale packs | **Zero by default** — opt-in custom adapter only |
|
|
15
|
+
| **Privacy Risk** | None (no host content read) | High (host text transmitted to provider if configured) |
|
|
16
|
+
| **User Consent** | Not required (local interface strings) | **Mandatory explicit consent** prior to transmission |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Provider Adapter Interface
|
|
21
|
+
|
|
22
|
+
Developers can configure custom translation providers by implementing `TranslationAdapter`:
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
export interface TranslationAdapter {
|
|
26
|
+
/** Unique provider identifier */
|
|
27
|
+
id: string;
|
|
28
|
+
/** Human-readable provider name */
|
|
29
|
+
name: string;
|
|
30
|
+
/** Optional provider description */
|
|
31
|
+
description?: string;
|
|
32
|
+
/** External privacy policy URL */
|
|
33
|
+
privacyPolicyUrl?: string;
|
|
34
|
+
/** Data retention policy */
|
|
35
|
+
dataRetention?: "none" | "transient" | "logged" | "model-training";
|
|
36
|
+
/** Geographical data residency location */
|
|
37
|
+
dataResidency?: string;
|
|
38
|
+
/** Allowed origins for security check */
|
|
39
|
+
allowedOrigins?: string[];
|
|
40
|
+
/** Supported BCP-47 language codes */
|
|
41
|
+
supportedTargetLanguages: string[] | (() => Promise<string[]>);
|
|
42
|
+
/** Translation function */
|
|
43
|
+
translate: (request: TranslationRequest) => Promise<TranslationResponse>;
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Request & Response Contracts
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
export interface TranslationRequest {
|
|
51
|
+
texts: string[];
|
|
52
|
+
sourceLanguage?: string;
|
|
53
|
+
targetLanguage: string;
|
|
54
|
+
signal?: AbortSignal;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export interface TranslatedItem {
|
|
58
|
+
original: string;
|
|
59
|
+
translated: string;
|
|
60
|
+
detectedSourceLanguage?: string;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export interface TranslationResponse {
|
|
64
|
+
translations: TranslatedItem[];
|
|
65
|
+
providerId: string;
|
|
66
|
+
timestamp: number;
|
|
67
|
+
attribution?: string;
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Privacy Threat Model & Security Boundaries
|
|
74
|
+
|
|
75
|
+
Host content translation involves reading user-facing DOM nodes. To guarantee privacy and prevent data leakage:
|
|
76
|
+
|
|
77
|
+
### 1. Sensitive Field Protection
|
|
78
|
+
|
|
79
|
+
The engine automatically scans element tags, attributes, and ancestor trees (`isSensitiveElement`) and rejects:
|
|
80
|
+
|
|
81
|
+
- **Passwords & Credentials**: `<input type="password">`, `[autocomplete*="password"]`, `[autocomplete*="current-password"]`, `[autocomplete*="new-password"]`.
|
|
82
|
+
- **Financial Information**: `[autocomplete*="cc-"]`, `[autocomplete*="credit"]`, `[autocomplete*="cvc"]`.
|
|
83
|
+
- **Personal Identifiers**: `<input type="email">`, `<input type="tel">`, `<input type="number">`, `[autocomplete*="email"]`, `[autocomplete*="username"]`.
|
|
84
|
+
- **Technical & Executable Code**: `<script>`, `<style>`, `<code>`, `<pre>`, `<kbd>`, `<samp>`, `<var>`, `<template>`.
|
|
85
|
+
- **Media & Embedded Objects**: `<iframe>`, `<svg>`, `<canvas>`, `<audio>`, `<video>`, `<object>`, `<embed>`.
|
|
86
|
+
- **Explicit Opt-Out Markers**: `[translate="no"]`, `class="notranslate"`, `[data-no-translate]`, `[data-sensitive]`.
|
|
87
|
+
- **Hidden Elements**: `[aria-hidden="true"]`, hidden inputs.
|
|
88
|
+
- **Widget Itself**: `[data-arap-portal]`, `[data-arap-widget]`, `.arap-widget-container`.
|
|
89
|
+
|
|
90
|
+
### 2. Cross-Origin & iframe Boundaries
|
|
91
|
+
|
|
92
|
+
- **Same-Origin Policy**: Browser security prevents reading content inside cross-origin `<iframe>` elements. Attempting to traverse cross-origin frames throws DOM security exceptions.
|
|
93
|
+
- **Architecture Guarantee**: All `<iframe>` elements are strictly excluded by `isSensitiveElement`. The adapter will never traverse, read, or inject into any frame.
|
|
94
|
+
|
|
95
|
+
### 3. Content Security Policy (CSP)
|
|
96
|
+
|
|
97
|
+
If a host application uses a remote translation API (e.g. Google Cloud, DeepL, LibreTranslate):
|
|
98
|
+
|
|
99
|
+
- The host's `connect-src` CSP directive must explicitly permit the provider endpoint:
|
|
100
|
+
```http
|
|
101
|
+
Content-Security-Policy: default-src 'self'; connect-src 'self' https://api.deepl.com;
|
|
102
|
+
```
|
|
103
|
+
- If an on-device local model (e.g., Transformers.js via WebAssembly or browser native Translation API `ai.translator`) is used, no external `connect-src` is required, though `wasm-unsafe-eval` may be needed for WebAssembly execution.
|
|
104
|
+
|
|
105
|
+
### 4. DOM Injection & XSS Prevention
|
|
106
|
+
|
|
107
|
+
- Translated output is assigned exclusively via `Text.textContent`.
|
|
108
|
+
- It is **never** parsed or injected through `innerHTML`.
|
|
109
|
+
- Any raw HTML or markup returned by a translation API is treated as plain text, eliminating script injection or Cross-Site Scripting (XSS) vectors.
|
|
110
|
+
|
|
111
|
+
### 5. Mandatory User Consent
|
|
112
|
+
|
|
113
|
+
- Zero requests occur on page load or widget opening.
|
|
114
|
+
- Translation requires an explicit user click on **"Review & Grant Consent"** and confirmation on the consent agreement.
|
|
115
|
+
- Consent can be revoked at any time via the **"Revoke Translation Consent"** button, immediately restoring original text.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Restoration & Teardown Lifecycle
|
|
120
|
+
|
|
121
|
+
Translations are completely non-destructive:
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
const session = await translateHostContent({
|
|
125
|
+
provider: myAdapter,
|
|
126
|
+
targetLanguage: "es",
|
|
127
|
+
consentRecord: userConsent,
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
// To revert back to original host text:
|
|
131
|
+
session.restore();
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
- Every translated node retains its original string in an internal closure record.
|
|
135
|
+
- Calling `session.restore()` resets all text nodes synchronously and idempotently.
|
|
136
|
+
- Unmounting the `TranslationController` or triggering display reset automatically executes restoration.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Example Custom Providers
|
|
141
|
+
|
|
142
|
+
### 1. Local Offline Mock (Default)
|
|
143
|
+
|
|
144
|
+
Included for zero-network development and testing:
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
import { createOfflineMockTranslationAdapter } from "accessibility-plugin-react";
|
|
148
|
+
|
|
149
|
+
const adapter = createOfflineMockTranslationAdapter({
|
|
150
|
+
prefix: "[ES]",
|
|
151
|
+
supportedLanguages: ["es", "fr", "de", "si", "ta"],
|
|
152
|
+
});
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### 2. Custom Remote API (e.g., DeepL / LibreTranslate)
|
|
156
|
+
|
|
157
|
+
```typescript
|
|
158
|
+
import type {
|
|
159
|
+
TranslationAdapter,
|
|
160
|
+
TranslationRequest,
|
|
161
|
+
} from "accessibility-plugin-react";
|
|
162
|
+
|
|
163
|
+
export const myRemoteAdapter: TranslationAdapter = {
|
|
164
|
+
id: "libretranslate-selfhosted",
|
|
165
|
+
name: "Self-Hosted LibreTranslate",
|
|
166
|
+
privacyPolicyUrl: "https://my-internal-host.com/privacy",
|
|
167
|
+
dataRetention: "none",
|
|
168
|
+
dataResidency: "internal-network",
|
|
169
|
+
supportedTargetLanguages: ["es", "fr", "de", "si", "ta"],
|
|
170
|
+
translate: async (req: TranslationRequest) => {
|
|
171
|
+
const res = await fetch("https://my-internal-host.com/translate", {
|
|
172
|
+
method: "POST",
|
|
173
|
+
headers: { "Content-Type": "application/json" },
|
|
174
|
+
body: JSON.stringify({
|
|
175
|
+
q: req.texts,
|
|
176
|
+
source: req.sourceLanguage || "auto",
|
|
177
|
+
target: req.targetLanguage,
|
|
178
|
+
}),
|
|
179
|
+
signal: req.signal,
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
const data = await res.json();
|
|
183
|
+
return {
|
|
184
|
+
translations: data.translatedText.map((t: string, i: number) => ({
|
|
185
|
+
original: req.texts[i],
|
|
186
|
+
translated: t,
|
|
187
|
+
})),
|
|
188
|
+
providerId: "libretranslate-selfhosted",
|
|
189
|
+
timestamp: Date.now(),
|
|
190
|
+
};
|
|
191
|
+
},
|
|
192
|
+
};
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Zero Compliance Claims
|
|
198
|
+
|
|
199
|
+
> **Important**: Machine-assisted translation does not constitute official WCAG 2.1/2.2 compliance, nor does it guarantee legal, medical, or regulatory accuracy. Translations are provided as an assistive convenience only.
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# Voice Navigation Research Prototype (A11Y-408)
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The Voice Navigation Research Prototype introduces user-initiated, browser-native voice commands for navigating page landmarks, controlling the accessibility panel, and scrolling page content. Built on the browser's native Web Speech Recognition API (`window.SpeechRecognition` or `window.webkitSpeechRecognition`), it executes entirely on the client side with strict privacy boundaries and zero persistent transcript or audio storage.
|
|
6
|
+
|
|
7
|
+
> [!WARNING]
|
|
8
|
+
> **Research Prototype Disclaimer**:
|
|
9
|
+
> Voice navigation is an experimental research prototype. Audio is processed solely through your browser's native Web Speech API during active listening sessions. No audio streams, recordings, or transcripts are stored locally or transmitted to external servers. Destructive actions, profile modifications, and form submissions are strictly excluded.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Architectural & Privacy Principles
|
|
14
|
+
|
|
15
|
+
### 1. Zero Audio Storage & Transmission
|
|
16
|
+
|
|
17
|
+
- **No recording persistence**: No audio streams, audio buffers, or media blobs are captured, recorded, or written to `localStorage`, `sessionStorage`, `IndexedDB`, or cookies.
|
|
18
|
+
- **No network requests**: The library makes zero external HTTP, WebSocket, or RPC calls. Speech recognition is handled exclusively by the client platform's built-in speech engine.
|
|
19
|
+
- **Ephemeral transcripts**: Recognized interim or final transcripts are processed in memory and immediately discarded. No history of spoken commands is retained.
|
|
20
|
+
|
|
21
|
+
### 2. Strict User-Initiated Consent
|
|
22
|
+
|
|
23
|
+
- **No auto-listen**: Microphone listening never activates automatically or on page load.
|
|
24
|
+
- **Explicit controls**: The user must explicitly click "Start Listening" to begin a session.
|
|
25
|
+
- **High-visibility listening status**: When listening is active, a pulsating microphone badge and polite ARIA live region (`aria-live="polite"`) inform the user that speech recognition is active.
|
|
26
|
+
|
|
27
|
+
### 3. Inactivity Watchdog Timeout
|
|
28
|
+
|
|
29
|
+
- **30-second silence watchdog**: If no speech command is detected for 30 consecutive seconds, listening automatically deactivates with a `timeout` state, preventing forgotten open microphones.
|
|
30
|
+
|
|
31
|
+
### 4. Background Tab Protection & Unmount Cleanup
|
|
32
|
+
|
|
33
|
+
- **Visibility change handling**: If the browser tab loses focus or visibility (`document.hidden`), speech recognition immediately aborts to protect acoustic privacy in shared environments.
|
|
34
|
+
- **Unload cleanup**: Session resources, timers, and listeners are cleanly destroyed on `beforeunload`, `pagehide`, and component unmount.
|
|
35
|
+
|
|
36
|
+
### 5. Safe Action Boundaries
|
|
37
|
+
|
|
38
|
+
- **Non-destructive only**: Only safe navigation (heading jump, viewport scrolling, menu open/close) is permitted. Form submissions, page reloads, profile changes, and arbitrary DOM interactions are strictly blocked.
|
|
39
|
+
|
|
40
|
+
### 6. Full Keyboard Alternatives
|
|
41
|
+
|
|
42
|
+
- **Universal access**: Every voice command is accompanied by a native, accessible keyboard button within the controller ("Next Heading", "Prev Heading", "Scroll Down", "Scroll Up", "Scroll Top", "Scroll Bottom").
|
|
43
|
+
- **Unsupported/Denied safety**: If the user's browser lacks speech recognition or if microphone permissions are denied, all keyboard alternatives remain 100% operational.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Supported Voice Command Set
|
|
48
|
+
|
|
49
|
+
The prototype recognizes an explicit, finite vocabulary of navigation and control commands:
|
|
50
|
+
|
|
51
|
+
| Command Identifier | Canonical Label | Recognized Spoken Phrases | Executed Action |
|
|
52
|
+
| :----------------- | :--------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
|
|
53
|
+
| `open_widget` | Open Widget | `"open"`, `"open widget"`, `"open panel"`, `"show widget"`, `"show panel"`, `"open menu"` | Opens the accessibility panel |
|
|
54
|
+
| `close_widget` | Close Widget | `"close"`, `"close widget"`, `"close panel"`, `"hide widget"`, `"hide panel"`, `"close menu"` | Closes the accessibility panel |
|
|
55
|
+
| `next_heading` | Next Heading | `"next heading"`, `"heading down"`, `"forward heading"`, `"go to next heading"` | Advances visual focus and smoothly scrolls to next DOM heading (`<h1>`–`<h6>`) |
|
|
56
|
+
| `previous_heading` | Previous Heading | `"previous heading"`, `"prior heading"`, `"heading up"`, `"back heading"`, `"go to previous heading"` | Moves focus and scrolls to previous DOM heading |
|
|
57
|
+
| `first_heading` | First Heading | `"first heading"`, `"top heading"`, `"start heading"`, `"main heading"` | Jumps directly to first DOM heading on the page |
|
|
58
|
+
| `scroll_down` | Scroll Down | `"scroll down"`, `"page down"`, `"down"`, `"move down"` | Scrolls window down by 75% of viewport height |
|
|
59
|
+
| `scroll_up` | Scroll Up | `"scroll up"`, `"page up"`, `"up"`, `"move up"` | Scrolls window up by 75% of viewport height |
|
|
60
|
+
| `scroll_top` | Scroll to Top | `"scroll top"`, `"top of page"`, `"go to top"`, `"scroll to top"`, `"jump to top"` | Scrolls smoothly to top of page (`top: 0`) |
|
|
61
|
+
| `scroll_bottom` | Scroll to Bottom | `"scroll bottom"`, `"bottom of page"`, `"go to bottom"`, `"scroll to bottom"`, `"jump to bottom"` | Scrolls smoothly to bottom of page |
|
|
62
|
+
| `stop_listening` | Stop Listening | `"stop"`, `"stop listening"`, `"cancel"`, `"turn off"`, `"exit voice"`, `"quit voice"` | Stops speech recognition and sets state to idle |
|
|
63
|
+
| `help` | Help / Commands | `"help"`, `"what can i say"`, `"commands"`, `"voice commands"`, `"list commands"` | Announces available voice commands via live feedback |
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Reduced Motion & Scrolling Behavior
|
|
68
|
+
|
|
69
|
+
When executing scroll commands or heading jumps:
|
|
70
|
+
|
|
71
|
+
- If `prefers-reduced-motion: reduce` is active in the user's operating system, or if the `reduceMotion` preference is enabled in the widget, scroll animations use `behavior: "auto"` (instant jump) instead of `"smooth"`.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Component Integration
|
|
76
|
+
|
|
77
|
+
### Default Rendering
|
|
78
|
+
|
|
79
|
+
`VoiceNavigationController` is included in the accessibility menu by default:
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
import {
|
|
83
|
+
AccessibilityPlugin,
|
|
84
|
+
AccessibilityButton,
|
|
85
|
+
AccessibilityList,
|
|
86
|
+
VoiceNavigationController,
|
|
87
|
+
} from "accessibility-plugin-react";
|
|
88
|
+
|
|
89
|
+
export function App() {
|
|
90
|
+
return (
|
|
91
|
+
<AccessibilityPlugin>
|
|
92
|
+
<AccessibilityButton />
|
|
93
|
+
<AccessibilityList>
|
|
94
|
+
<VoiceNavigationController />
|
|
95
|
+
</AccessibilityList>
|
|
96
|
+
</AccessibilityPlugin>
|
|
97
|
+
);
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Custom Event Callbacks
|
|
102
|
+
|
|
103
|
+
When optional privacy-safe event callbacks are configured on the provider, voice actions dispatch structured `feature-change` events without revealing spoken text or audio:
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
<AccessibilityPlugin
|
|
107
|
+
onFeatureEvent={(event) => {
|
|
108
|
+
if (event.type === "feature-change" && event.feature === "voiceNavigation") {
|
|
109
|
+
console.log("Voice navigation state:", event.value);
|
|
110
|
+
}
|
|
111
|
+
}}
|
|
112
|
+
>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Browser Support & Fallback Matrix
|
|
118
|
+
|
|
119
|
+
| Engine / Browser | Native Web Speech Support | Fallback Behavior |
|
|
120
|
+
| :--------------------------------- | :------------------------------------- | :--------------------------------------------------------------------- |
|
|
121
|
+
| **Chromium** (Chrome, Edge, Brave) | Supported (`webkitSpeechRecognition`) | Full voice recognition and keyboard buttons |
|
|
122
|
+
| **Safari / WebKit** | Supported (`webkitSpeechRecognition`) | Full voice recognition and keyboard buttons |
|
|
123
|
+
| **Firefox (Gecko)** | Disabled by default in desktop Firefox | Disabled toggle with "Voice Unavailable" notice; full keyboard buttons |
|
|
124
|
+
| **Mobile WebKit / Chrome Mobile** | Supported with microphone consent | Full voice recognition and touch/keyboard buttons |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "accessibility-plugin-react",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.28.0",
|
|
4
4
|
"description": "A composable React display-preference widget with a clean light design, persistent settings and movable accessible controls.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"module": "dist/index.mjs",
|