accessibility-plugin-react 2.18.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 +42 -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 +193 -23
- package/docs/BUILD_AND_RELEASE_PLAN.md +16 -16
- package/docs/DIAGNOSTICS.md +119 -0
- package/docs/DICTIONARY.md +154 -0
- package/docs/FEATURES.md +83 -31
- 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/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
|
@@ -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",
|