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.
@@ -0,0 +1,150 @@
1
+ # Supported browser, device, and assistive-technology matrix
2
+
3
+ This document details the compatibility matrix, verification methods, responsive and display modes, touch and pointer specifications, assistive technology semantics, and explicit boundaries for `accessibility-plugin-react`.
4
+
5
+ > **Important**: Automated test suites (Playwright, Axe Core, Vitest) verify technical compliance, DOM contracts, and baseline accessibility semantics. Automated audits **do not establish full WCAG compliance or substitute for human assistive technology acceptance**. Human testing with physical devices, screen readers, and actual users remains required for host applications.
6
+
7
+ ---
8
+
9
+ ## 1. Browser engine and environment matrix
10
+
11
+ All browser environments are tested using real browser engines in clean, packed-consumer production builds (React 18, React 19 with Tailwind CSS, Next.js App Router, and Vite).
12
+
13
+ | Platform / Engine | Tested Versions | Automated Status | Known Behaviors & Safeguards |
14
+ | :---------------------------------------- | :----------------------------------------------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15
+ | **Chromium** (Chrome, Edge, Brave, Opera) | Chromium 120+ (Playwright 1.64.0 / Chromium 156) | **Verified (CI & Local)** | Full support for all filter pipelines, CSS variables, `forced-colors`, pointer capture, and Web Speech API. |
16
+ | **Gecko / Firefox** (Firefox Desktop) | Firefox 120+ (Playwright Linux CI & Desktop) | **Verified (CI)** | Full CSS filter, zoom, and font replacement support. Web Speech synthesis in headless Linux CI requires graceful degradation due to absence of system audio sinks. |
17
+ | **WebKit** (Safari Desktop) | WebKit 17+ (Playwright WebKit 27.2) | **Verified (CI & Local)** | WebKit requires programmatic focus transfer targets (such as `<main id="host">`) to have `tabIndex={-1}` when navigating via landmark skip links. Non-standard subpixel fractional geometry is handled with tolerance assertions. |
18
+ | **Mobile WebKit** (iOS Safari) | iOS 16+, iPhone 13/14 emulation | **Verified (CI & Local)** | Full touch target compliance ($\ge 44\text{px} \times 44\text{px}$). Respects `env(safe-area-inset-*)`. Pointer drag events use pointer capture and prevent unwanted page scrolling during widget repositioning. |
19
+ | **Chromium for Android** | Chrome Mobile emulation (Pixel 5/7) | **Verified (Local)** | Full touch target compliance ($\ge 44\text{px} \times 44\text{px}$). Safe area support. |
20
+
21
+ ---
22
+
23
+ ## 2. React and framework compatibility
24
+
25
+ The package ships pre-bundled ESM, CommonJS, TypeScript declarations (`.d.ts`), and scoped CSS without requiring external styling dependencies or build-time transforms.
26
+
27
+ | Framework / Runtime | Versions Tested | Verification Scope | Status |
28
+ | :------------------------- | :-------------------------------- | :--------------------------------------------------------------------------------- | :----------- |
29
+ | **React 18** | 18.3.1 | Clean packed npm tarball, Vite CSR, Vitest unit suite | **Verified** |
30
+ | **React 19** | 19.0.0, 19.2.0 | Clean packed npm tarball, Vite CSR, Tailwind CSS 3/4 integration | **Verified** |
31
+ | **Next.js (App Router)** | 14.x, 15.x, 16.x (`next@16.2.10`) | Production webpack build, Server Component imports, SSR hydration, client boundary | **Verified** |
32
+ | **Next.js (Pages Router)** | 14.x, 15.x, 16.x | Production SSR and client-side navigation | **Verified** |
33
+ | **Node.js** | >= 22.13.0 (Node 22 LTS, Node 24) | `npm ci`, `npm pack`, build scripts, consumer installations | **Verified** |
34
+
35
+ ---
36
+
37
+ ## 3. Responsive viewports and zoom modes
38
+
39
+ The plugin is designed to withstand aggressive browser zoom and extreme viewport reflow without layout breakage, clipping, or loss of functionality.
40
+
41
+ ### 400% Zoom Reflow (WCAG 1.4.10)
42
+
43
+ - **Standard Baseline**: A desktop viewport of 1280px zoomed to 400% scales CSS layout down to a **320px viewport width**.
44
+ - **Panel Reflow**: The accessibility panel constrains its maximum width to `100vw` (clamped to `min(360px, calc(100vw - 32px))`), preventing horizontal viewport scrollbars on the host page (`el.scrollWidth <= el.clientWidth + 1`).
45
+ - **Internal Scrolling**: The control tools list (`.arap-tools-list`) scrolls independently with smooth vertical overflow, keeping header titles, close buttons, and footer reset actions fixed and immediately reachable.
46
+
47
+ ### 200% Text Zoom / Font Scaling
48
+
49
+ - Font scale controls step smoothly between 100% and 200% using scalable `rem` / proportional calculations without truncating button text or causing overlapping elements.
50
+
51
+ ### Safe Areas (`env(safe-area-inset-*)`)
52
+
53
+ - The floating launcher button and open panel respect device notches, home indicator bars, and display cutouts by padding bounds with:
54
+ ```css
55
+ top: max(16px, env(safe-area-inset-top));
56
+ bottom: max(16px, env(safe-area-inset-bottom));
57
+ left: max(16px, env(safe-area-inset-left));
58
+ right: max(16px, env(safe-area-inset-right));
59
+ ```
60
+
61
+ ---
62
+
63
+ ## 4. High contrast and system color schemes
64
+
65
+ ### Forced Colors / Windows High Contrast Mode (`forced-colors: active`)
66
+
67
+ - **Filter Suppression**: When `forced-colors: active` is detected, the core filter composition engine (`composeFilter()`) automatically returns an empty string `""`. This guarantees that CSS filters (`invert()`, `contrast()`, `saturate()`, `grayscale()`) **never distort or override the user's high-contrast operating system colors**.
68
+ - **System Palette Keywords**: Controls, borders, and focus rings utilize system color tokens such as `CanvasText`, `LinkText`, `ButtonBorder`, and `Highlight` to integrate seamlessly with OS color choices.
69
+ - **Explicit Borders**: Interactive elements feature solid CSS borders so that controls remain distinctly outlined even when background colors are overridden by the user agent.
70
+
71
+ ### Dark, Light, and System Themes
72
+
73
+ - Built-in Clean Light theme uses CSS variables scoped under `.arap-root` and `.arap-panel`.
74
+ - Adapts smoothly when embedded in dark-themed host applications without bleeding host styles into the widget or widget styles into the host application.
75
+
76
+ ### Reduced Motion (`prefers-reduced-motion: reduce`)
77
+
78
+ - All panel transitions, accordion expansions, and reading guide smooth scrolling are disabled or instantaneous when the user requests reduced motion:
79
+ ```css
80
+ @media (prefers-reduced-motion: reduce) {
81
+ *,
82
+ *::before,
83
+ *::after {
84
+ animation-duration: 0.01ms !important;
85
+ animation-iteration-count: 1 !important;
86
+ transition-duration: 0.01ms !important;
87
+ scroll-behavior: auto !important;
88
+ }
89
+ }
90
+ ```
91
+
92
+ ---
93
+
94
+ ## 5. Touch and pointer target specifications
95
+
96
+ ### Minimum Target Size (WCAG 2.5.5 / WCAG 2.5.8)
97
+
98
+ - Every interactive button within the launcher, panel, control cards, stepper controls, choice selectors, and quick-action footers satisfies a minimum clickable/tappable bounding box of **$44\text{px} \times 44\text{px}$**.
99
+ - Continuous Playwright browser tests assert that all visible buttons maintain `box.width >= 44` and `box.height >= 44` under both desktop and mobile viewports.
100
+
101
+ ### Pointer and Drag Interactions
102
+
103
+ - **Pointer Capture**: Widget repositioning uses pointer events (`onPointerDown`, `setPointerCapture`, `onPointerUp`) rather than HTML5 drag-and-drop, guaranteeing smooth movement across touchscreens, trackpads, and mice.
104
+ - **Cancellation**: Pressing the `Escape` key during an active drag operation immediately cancels the drag and restores the widget to its prior persisted coordinates.
105
+ - **Boundary Clamping**: The widget cannot be dragged off-screen or hidden behind browser chrome or taskbars.
106
+ - **Non-Drag Position Controls**: For users unable to drag, dedicated positioning controls in the panel allow relocating the widget to any screen corner or resetting position via standard keyboard clicks.
107
+
108
+ ---
109
+
110
+ ## 6. Assistive technology and semantic structure
111
+
112
+ ### Screen Reader Support
113
+
114
+ The widget's controls are tested with standard screen reading technologies:
115
+
116
+ - **NVDA** (Windows) with Chrome / Firefox / Edge
117
+ - **JAWS** (Windows) with Chrome / Edge
118
+ - **VoiceOver** (macOS & iOS) with Safari
119
+ - **TalkBack** (Android) with Chrome
120
+
121
+ ### Semantic DOM & ARIA Landmarks
122
+
123
+ - **Launcher**: Native `<button type="button">` with descriptive `aria-label="Accessibility"` and `aria-expanded="true|false"`.
124
+ - **Panel Container**: Non-modal `<section>` or `<div>` with `role="region"` and `aria-label="Accessibility settings"`. Does not trap focus or block interaction with the underlying page.
125
+ - **Controls**:
126
+ - Toggles: Semantic switches with `role="switch"` and `aria-checked="true|false"`.
127
+ - Radios / Choices: Native radio inputs or `role="radiogroup"` with keyboard arrow-key navigation.
128
+ - Steppers: Increment and decrement buttons with explicit accessible labels and current value announcements.
129
+ - **Live Announcements**: Polite live regions (`role="status"`, `aria-live="polite"`, `aria-atomic="true"`) announce state changes, search filter counts, and reset confirmations without interrupting speech.
130
+ - **Focus Management**:
131
+ - Opening the panel focuses the close button or first interactive element.
132
+ - Closing the panel returns focus cleanly to the launcher trigger button.
133
+ - If the widget is unmounted dynamically, focus safely falls back to `document.body` or host layout without throwing errors.
134
+
135
+ ---
136
+
137
+ ## 7. Explicit boundaries and architectural limits
138
+
139
+ To avoid overpromising or compromising host application stability, the following boundaries are explicitly defined:
140
+
141
+ 1. **No Universal WCAG Compliance Claim**:
142
+ Installing this plugin does not automatically make an inaccessible website compliant. It provides assistive display preferences for end users.
143
+ 2. **Shadow DOM**:
144
+ CSS variables and filter effects applied to `document.documentElement` or host containers do not pierce closed Shadow DOM roots.
145
+ 3. **Cross-Origin Iframes**:
146
+ Browsers enforce the Same-Origin Policy. The plugin cannot inspect, style, or translate content hosted inside cross-origin `<iframe>` elements.
147
+ 4. **Platform Speech Synthesis Constraints**:
148
+ Native Text-to-Speech (TTS) relies on the browser's `window.speechSynthesis` API. In environments lacking audio drivers or speech synthesis services (e.g., headless Linux servers without mock audio sinks), audio playback cannot be synthesized.
149
+ 5. **Zero Data Transmission**:
150
+ All user preferences, profiles, and state remain purely local in `localStorage` under `react-accessibility-plugin:state`. No analytics, telemetry, or user inputs are ever transmitted over the network.
@@ -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.18.0",
3
+ "version": "2.28.1",
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",
@@ -22,6 +22,7 @@
22
22
  "files": [
23
23
  "dist",
24
24
  "LICENSE",
25
+ "NOTICE",
25
26
  "docs"
26
27
  ],
27
28
  "scripts": {