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.
@@ -0,0 +1,154 @@
1
+ # Dictionary Provider Interface & Local Fallback (A11Y-403)
2
+
3
+ ## Overview
4
+
5
+ The `accessibility-plugin-react` library includes an accessible terminology dictionary and customizable dictionary provider interface (`DictionaryController` and `core/dictionary.ts`).
6
+
7
+ It enables users to look up digital accessibility terms, WCAG definitions, and web terminology directly inside the application with **zero network transmission by default**, **strict privacy protection**, and **truthful responses without hallucination**.
8
+
9
+ ---
10
+
11
+ ## Core Principles & Guarantees
12
+
13
+ ### 1. Explicit User Action Only
14
+
15
+ - Dictionary lookups **only occur on deliberate, explicit user action** (typing in the search field and pressing Enter or clicking "Look up").
16
+ - **Never looks up on hover, focus, text selection, or route change.** This prevents accidental network queries, distraction for screen-reader users, and unexpected interface layout shifts.
17
+
18
+ ### 2. Zero Network Requests by Default (100% Offline Static Fallback)
19
+
20
+ - In default configuration (`provider` is null or undefined), the dictionary operates 100% locally from built-in static glossaries.
21
+ - The browser `fetch()` API and network stack are **never invoked** when the provider is off.
22
+ - Built-in curated terms cover key accessibility and digital concepts in **English (`en`)**, **Sinhala (`si`)**, and **Tamil (`ta`)**:
23
+ - `accessibility` / `ප්‍රවේශ්‍යතාව` / `அணுகல்தன்மை`
24
+ - `aria`
25
+ - `contrast` / `වර්ණ වෙනස` / `மாறுபட்ட வண்ணம்`
26
+ - `dyslexia`
27
+ - `focus`
28
+ - `grayscale` / `අළු පරිමාණය` / `சாம்பல் நிறம்`
29
+ - `reflow`
30
+ - `saturation` / `සන්තෘප්තිය` / `நிறச்செறிவூட்டல்`
31
+ - `screen reader`
32
+ - `semantic`
33
+ - `wcag`
34
+
35
+ ### 3. Truthful Unknown Results (Never Hallucinates)
36
+
37
+ - When a requested word is not present in the dictionary, the engine **never fabricates or hallucinates a definition**.
38
+ - It returns `{ found: false }` with honest messaging: `"No definition found for '<term>'. Check your spelling or try a suggestion below."`
39
+ - Suggestion matching offers clickable chips for partially matched terms without fabricating definitions.
40
+
41
+ ### 4. Strict Sanitization & Sensitive Data Rejection
42
+
43
+ Before any term is searched locally or passed to an external provider:
44
+
45
+ - **HTML tags & control characters are stripped**: `<script>`, `<b>`, etc.
46
+ - **Length is strictly capped**: Maximum 50 characters to prevent buffer and memory abuse.
47
+ - **Sensitive data is rejected**: Terms matching email addresses, URLs, credit card numbers, auth tokens (`Bearer ...`, JWTs, API keys) are immediately rejected with an advisory message: `"Private or sensitive content cannot be looked up."`
48
+ - **Combining mark preservation**: Unicode combining marks (`\p{M}`) are preserved to support Indic and complex scripts (Sinhala, Tamil, etc.).
49
+ - **Privacy shield**: Whole-page DOM contents, cookies, form values, and clipboard contents are **never** transmitted to providers.
50
+
51
+ ### 5. Focus Management & Restoration
52
+
53
+ - When the dialog opens, keyboard focus transfers immediately into the search input.
54
+ - Focus is trapped within the dialog while open (`Tab` and `Shift+Tab` cycle between focusable controls).
55
+ - Pressing `Escape` or clicking the `Close dictionary` button dismisses the dialog and **instantly returns keyboard focus to the triggering button**.
56
+
57
+ ---
58
+
59
+ ## Architecture & Provider Interface
60
+
61
+ Developers can configure a custom remote dictionary backend by supplying an implementation of `DictionaryProvider`:
62
+
63
+ ```typescript
64
+ export interface DictionaryEntry {
65
+ word: string;
66
+ phonetic?: string;
67
+ partOfSpeech?: string;
68
+ definition: string;
69
+ example?: string;
70
+ source: "local" | "custom" | "provider";
71
+ language?: string;
72
+ }
73
+
74
+ export interface DictionaryLookupResult {
75
+ found: boolean;
76
+ term?: string;
77
+ entry?: DictionaryEntry;
78
+ suggestions?: string[];
79
+ error?: string;
80
+ }
81
+
82
+ export interface DictionaryProvider {
83
+ id: string;
84
+ name: string;
85
+ lookup: (word: string, lang?: string) => Promise<DictionaryLookupResult>;
86
+ allowedOrigins?: string[];
87
+ rateLimitMs?: number;
88
+ }
89
+ ```
90
+
91
+ ### Rate Limiting & Graceful Fallback
92
+
93
+ - `lookupWord()` enforces per-provider rate limiting (default 400ms minimum interval) to avoid query flooding.
94
+ - If a custom provider throws a network timeout or HTTP error, the system **automatically falls back to the local static glossary**.
95
+
96
+ ---
97
+
98
+ ## Usage Example
99
+
100
+ ### Basic Setup (100% Offline)
101
+
102
+ ```tsx
103
+ import {
104
+ AccessibilityPlugin,
105
+ AccessibilityButton,
106
+ AccessibilityList,
107
+ DictionaryController,
108
+ } from "accessibility-plugin-react";
109
+
110
+ export function App() {
111
+ return (
112
+ <AccessibilityPlugin>
113
+ <AccessibilityButton />
114
+ <AccessibilityList>
115
+ <DictionaryController />
116
+ </AccessibilityList>
117
+ </AccessibilityPlugin>
118
+ );
119
+ }
120
+ ```
121
+
122
+ ### With Configured Remote Provider
123
+
124
+ ```tsx
125
+ import {
126
+ DictionaryController,
127
+ type DictionaryProvider,
128
+ } from "accessibility-plugin-react";
129
+
130
+ const myApiProvider: DictionaryProvider = {
131
+ id: "internal-wiki",
132
+ name: "Corporate Terminology Service",
133
+ rateLimitMs: 500,
134
+ lookup: async (word: string, lang?: string) => {
135
+ const response = await fetch(
136
+ `/api/dictionary?q=${encodeURIComponent(word)}&lang=${lang}`,
137
+ );
138
+ if (!response.ok) throw new Error("Service error");
139
+ return response.json();
140
+ },
141
+ };
142
+
143
+ export function CustomTools() {
144
+ return <DictionaryController provider={myApiProvider} />;
145
+ }
146
+ ```
147
+
148
+ ---
149
+
150
+ ## Keyboard Shortcuts
151
+
152
+ - Default shortcut: **`Alt+D`** (customizable via `KeyboardShortcutsController`).
153
+ - Dialog navigation: **`Tab`** / **`Shift+Tab`** to cycle controls.
154
+ - Dialog dismissal: **`Escape`** (restores focus to trigger button).
package/docs/FEATURES.md CHANGED
@@ -2,36 +2,43 @@
2
2
 
3
3
  All features are opt-in via controllers, use native buttons, support Enter/Space and ordinary Tab order, and expose pressed/disabled state or a polite numeric output. Defaults leave the host unchanged. Values persist once changed and return to defaults on Reset All. Effects persist when controls/panel disappear and are cleaned on provider removal. Widget portals are excluded. The engine restores prior inline properties and priorities instead of simply deleting them.
4
4
 
5
- | Controller / key | Default; states and bounds | Host behavior / edge cases |
6
- | ------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
7
- | TextScaleController / fontScale | 1.0; 1.0, 1.125, 1.25, 1.5, 2.0 (stepwise) | Reflow-safe stepwise text enlargement without CSS transforms or compounding. Protects forms, labels, code, icons, widget, and exempt content. |
8
- | FontSizeController / fontSize | 100; 50–200%, step 10 or stepwise | Scales computed font size and line height together. Supports optional `stepScale` / `steps` props; protects forms, labels, code blocks, icons, and widget UI. |
9
- | LineHeightController / lineHeight | 100; 50–200%, step 10 or stepwise presets | Scales computed line height. Supports `stepPresets` (100%, 150%, 175%, 200% / 1.0x, 1.5x, 1.75x, 2.0x) and custom `steps`. Excludes tables, code blocks, controls, and widget UI. |
10
- | LetterSpacingController / letterSpacing | 0; 0–10px, step 1 | Sets letter spacing on content elements. Protects cursive/Arabic/RTL scripts (disabled) and Indic/Sinhala/Tamil scripts (clamped <=1px). Excludes tables, code, and controls. |
11
- | WordSpacingController / wordSpacing | 0; 0–10px, step 1 | Sets word spacing on content elements while protecting tables, code, controls, and widget UI. |
12
- | ParagraphSpacingController / paragraphSpacing | 0; 0–32px, step 4 | Increases paragraph bottom margin (`p`, `[role="paragraph"]`) while protecting tables, code, and controls. |
13
- | ContrastController / contrast | 0; 0/1/2/3, light, dark, high, invert, reduced, named palettes | Off, 1.25×, 1.5×, 2×; reduced=0.5×. Semantic light, dark, high contrast, and invert tokens protect images/video/SVG/charts and validation states. Bypasses overrides when OS forced-colors is active. |
14
- | ContrastModeController / contrastMode | off; off/light/dark/high/invert | Semantic light, dark, high contrast, and media-safe invert modes. Preserves images, charts, and validation errors. Native forced-colors protection. See docs/CONTRAST.md. |
15
- | SaturationController / saturation | 0; 0/1/2 | Off, 0.2×, 2× saturation. Composes with other filters. |
16
- | InvertColorsController / invertColors | false; boolean | Adds invert(1), includes content images. |
17
- | GrayscaleController / grayscale | false; boolean | Adds grayscale(1); saturation cannot restore color while this is active. |
18
- | LinkHighlightController / linkHighlight | false; false/true/underline/palettes | Non-color underline cues (2px thickness, 3px offset) and high-contrast palettes. Preserves disabled links and system LinkText in forced colors. See docs/LINKS_AND_FOCUS.md. |
19
- | HighlightFocusController / highlightFocus | false; boolean | High-visibility dual-ring focus outline (3px blue + 5px white halo) with forced-colors Highlight support. Preserves disabled controls. See docs/LINKS_AND_FOCUS.md. |
20
- | SkipToMainLink / findMainLandmark | Dynamic helper / link | Authentic skip-to-main landmark link. Only renders when a real `<main>` or `[role="main"]` exists. Transfers focus and scrolls into view. See docs/LINKS_AND_FOCUS.md. |
21
- | TextAlignController / textAlign | default; default/left/center/right/justify | Scoped strictly to logical text blocks (p, headings, lists, blockquotes); excludes tables, form controls, and code. Justification displays an accessible WCAG SC 1.4.8 advisory warning. |
22
- | FontFamilyController / fontFamily | default; default/legible/dyslexia-option | Applies clean system-ui or OpenDyslexic with Sinhala/Tamil fallbacks. Code blocks, icons, and SVGs are protected. See docs/FONTS.md. |
23
- | HideImagesController / HideDecorativeImagesController / hideImages | false; boolean | Hides only eligible decorative img/picture (alt="", role="presentation", role="none", aria-hidden="true", data-decorative) and removes decorative CSS background images. Strictly preserves interactive controls, CAPTCHA, charts, maps, QR codes, and informative images. Never fabricates alt text. See docs/DECORATIVE_IMAGES.md. |
24
- | HideVideosController / hideVideos | false; boolean | Hides video and recognized YouTube/Vimeo embed URL patterns. Does not hide unrelated iframe documents, pause video or mute audio. |
25
- | ReduceMotionController / reduceMotion | false; boolean | Scoped CSS animation and smooth-scroll suppression, tracked WAAPI animation pausing, and explicit media autoplay pause. Honors OS prefers-reduced-motion. See docs/REDUCE_MOTION.md. |
26
- | BigCursorController / bigCursor | false; boolean | 40px high-contrast pointer via SVG cursor with native fallback. Capability-aware: detects `(pointer: fine)` and suppresses styles on touch-only hardware. Host CSS cursor effects are restored. See docs/READING_AIDS.md. |
27
- | ReadingMaskController / readingMask | false; boolean / number (height) | Transparent reading aperture window with surrounding screen dimmed. Adjustable height (default 100px, 40–400px), stepper controls, pointer/touch/focus/scroll tracking, Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
28
- | ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border. Pointer-transparent (`pointer-events: none !important`), never blocks clicks/selection/focus. Follows pointer, touch drag, keyboard focus, and scroll. Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
29
- | TooltipsController / AccessibleTooltipsController / tooltips | false; boolean | Displays authored descriptions (`aria-description`, `aria-describedby`, `aria-label`, `alt`, `title`) on hover and focus. Strictly excludes sensitive/password fields. WCAG 2.1 SC 1.4.13 compliant (Escape dismissal, hoverable, persistent, viewport clamped). See docs/TOOLTIPS.md. |
30
- | PageNavigatorController / HeadingsNavigatorController / PageStructureController | Action dialog; no persistent preference | Scans real DOM headings (`h1`–`h6`) and named landmarks (`banner`, `navigation`, `main`, `region`, etc.). Safe scroll and focus with temporary tabindex cleanup, live mutation updates without loops, and search filtering. See docs/PAGE_NAVIGATOR.md. |
31
- | ProfilesController / ProfileController / AccessibilityProfilesController | activeProfile; ProfilePresetId / null | Previews, applies, and reverts eight neutral presets (Motor, Blind, Color Blind, Dyslexia, Low Vision, Cognitive, Seizure, ADHD). Follows deterministic override model where user explicit choices survive reversal. Zero implicit audio/mic. See docs/PROFILES.md. |
32
- | PresetsController / CustomPresetsController / SettingsImportExportController | customPresets; CustomPreset[] | Saves named user presets, 1-click apply/delete, and versioned JSON backup and transfer. Strict privacy exclusions discard private data, transcripts, and credentials. Saved presets library survives display reset. See docs/PRESETS.md. |
33
- | Locales & i18n (`en`, `si`, `si-LK`, `ta`, `ta-LK`) | LocaleStrings / `locale` prop | Reviewed English, Sinhala, and Tamil locale packs with typography fallbacks and full RTL infrastructure. Automatic `document.documentElement.lang` resolution; host content is never translated. See docs/LOCALES.md. |
34
- | ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
5
+ | Controller / key | Default; states and bounds | Host behavior / edge cases |
6
+ | --------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7
+ | TextScaleController / fontScale | 1.0; 1.0, 1.125, 1.25, 1.5, 2.0 (stepwise) | Reflow-safe stepwise text enlargement without CSS transforms or compounding. Protects forms, labels, code, icons, widget, and exempt content. |
8
+ | FontSizeController / fontSize | 100; 50–200%, step 10 or stepwise | Scales computed font size and line height together. Supports optional `stepScale` / `steps` props; protects forms, labels, code blocks, icons, and widget UI. |
9
+ | LineHeightController / lineHeight | 100; 50–200%, step 10 or stepwise presets | Scales computed line height. Supports `stepPresets` (100%, 150%, 175%, 200% / 1.0x, 1.5x, 1.75x, 2.0x) and custom `steps`. Excludes tables, code blocks, controls, and widget UI. |
10
+ | LetterSpacingController / letterSpacing | 0; 0–10px, step 1 | Sets letter spacing on content elements. Protects cursive/Arabic/RTL scripts (disabled) and Indic/Sinhala/Tamil scripts (clamped <=1px). Excludes tables, code, and controls. |
11
+ | WordSpacingController / wordSpacing | 0; 0–10px, step 1 | Sets word spacing on content elements while protecting tables, code, controls, and widget UI. |
12
+ | ParagraphSpacingController / paragraphSpacing | 0; 0–32px, step 4 | Increases paragraph bottom margin (`p`, `[role="paragraph"]`) while protecting tables, code, and controls. |
13
+ | ContrastController / contrast | 0; 0/1/2/3, light, dark, high, invert, reduced, named palettes | Off, 1.25×, 1.5×, 2×; reduced=0.5×. Semantic light, dark, high contrast, and invert tokens protect images/video/SVG/charts and validation states. Bypasses overrides when OS forced-colors is active. |
14
+ | ContrastModeController / contrastMode | off; off/light/dark/high/invert | Semantic light, dark, high contrast, and media-safe invert modes. Preserves images, charts, and validation errors. Native forced-colors protection. See docs/CONTRAST.md. |
15
+ | SmartContrastController / smartContrast | off; off/aa/aaa (or false/true) | Opt-in measured smart contrast research prototype. Evaluates foreground relative luminance against computed backdrop without layout thrashing; blends semi-transparent ancestor layers; reports unsupported gradients/images; restores styles on reset. See docs/SMART_CONTRAST.md. |
16
+ | SaturationController / saturation | 0; 0/1/2/3, "original"/"low"/"high"/"grayscale" | Off, 0.2× (Low), 2× (High), and Grayscale modes. Composes with other filters. Features accessible chart/image advisory warnings and forced-colors bypass. See docs/SATURATION_AND_GRAYSCALE.md. |
17
+ | InvertColorsController / invertColors | false; boolean | Adds invert(1), includes content images. |
18
+ | GrayscaleController / grayscale | false; boolean | Adds grayscale(1) monochrome mode. Displays accessible visualization advisory warning and respects OS forced-colors. See docs/SATURATION_AND_GRAYSCALE.md. |
19
+ | LinkHighlightController / linkHighlight | false; false/true/underline/palettes | Non-color underline cues (2px thickness, 3px offset) and high-contrast palettes. Preserves disabled links and system LinkText in forced colors. See docs/LINKS_AND_FOCUS.md. |
20
+ | HighlightFocusController / highlightFocus | false; boolean | High-visibility dual-ring focus outline (3px blue + 5px white halo) with forced-colors Highlight support. Preserves disabled controls. See docs/LINKS_AND_FOCUS.md. |
21
+ | SkipToMainLink / findMainLandmark | Dynamic helper / link | Authentic skip-to-main landmark link. Only renders when a real `<main>` or `[role="main"]` exists. Transfers focus and scrolls into view. See docs/LINKS_AND_FOCUS.md. |
22
+ | TextAlignController / textAlign | default; default/left/center/right/justify | Scoped strictly to logical text blocks (p, headings, lists, blockquotes); excludes tables, form controls, and code. Justification displays an accessible WCAG SC 1.4.8 advisory warning. |
23
+ | FontFamilyController / fontFamily | default; default/legible/dyslexia-option | Applies clean system-ui or OpenDyslexic with Sinhala/Tamil fallbacks. Code blocks, icons, and SVGs are protected. See docs/FONTS.md. |
24
+ | HideImagesController / HideDecorativeImagesController / hideImages | false; boolean | Hides only eligible decorative img/picture (alt="", role="presentation", role="none", aria-hidden="true", data-decorative) and removes decorative CSS background images. Strictly preserves interactive controls, CAPTCHA, charts, maps, QR codes, and informative images. Never fabricates alt text. See docs/DECORATIVE_IMAGES.md. |
25
+ | HideVideosController / hideVideos | false; boolean | Hides video and recognized YouTube/Vimeo embed URL patterns. Does not hide unrelated iframe documents, pause video or mute audio. |
26
+ | ReduceMotionController / reduceMotion | false; boolean | Scoped CSS animation and smooth-scroll suppression, tracked WAAPI animation pausing, and explicit media autoplay pause. Honors OS prefers-reduced-motion. See docs/REDUCE_MOTION.md. |
27
+ | BigCursorController / bigCursor | false; boolean | 40px high-contrast pointer via SVG cursor with native fallback. Capability-aware: detects `(pointer: fine)` and suppresses styles on touch-only hardware. Host CSS cursor effects are restored. See docs/READING_AIDS.md. |
28
+ | ReadingMaskController / readingMask | false; boolean / number (height) | Transparent reading aperture window with surrounding screen dimmed. Adjustable height (default 100px, 40–400px), stepper controls, pointer/touch/focus/scroll tracking, Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
29
+ | ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border. Pointer-transparent (`pointer-events: none !important`), never blocks clicks/selection/focus. Follows pointer, touch drag, keyboard focus, and scroll. Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
30
+ | TooltipsController / AccessibleTooltipsController / tooltips | false; boolean | Displays authored descriptions (`aria-description`, `aria-describedby`, `aria-label`, `alt`, `title`) on hover and focus. Strictly excludes sensitive/password fields. WCAG 2.1 SC 1.4.13 compliant (Escape dismissal, hoverable, persistent, viewport clamped). See docs/TOOLTIPS.md. |
31
+ | PageNavigatorController / HeadingsNavigatorController / PageStructureController | Action dialog; no persistent preference | Scans real DOM headings (`h1`–`h6`) and named landmarks (`banner`, `navigation`, `main`, `region`, etc.). Safe scroll and focus with temporary tabindex cleanup, live mutation updates without loops, and search filtering. See docs/PAGE_NAVIGATOR.md. |
32
+ | ProfilesController / ProfileController / AccessibilityProfilesController | activeProfile; ProfilePresetId / null | Previews, applies, and reverts eight neutral presets (Motor, Blind, Color Blind, Dyslexia, Low Vision, Cognitive, Seizure, ADHD). Follows deterministic override model where user explicit choices survive reversal. Zero implicit audio/mic. See docs/PROFILES.md. |
33
+ | PresetsController / CustomPresetsController / SettingsImportExportController | customPresets; CustomPreset[] | Saves named user presets, 1-click apply/delete, and versioned JSON backup and transfer. Strict privacy exclusions discard private data, transcripts, and credentials. Saved presets library survives display reset. See docs/PRESETS.md. |
34
+ | Locales & i18n (`en`, `si`, `si-LK`, `ta`, `ta-LK`) | LocaleStrings / `locale` prop | Reviewed English, Sinhala, and Tamil locale packs with typography fallbacks and full RTL infrastructure. Automatic `document.documentElement.lang` resolution; host content is never translated. See docs/LOCALES.md. |
35
+ | ReadingModeController / readingMode | false; boolean | Non-destructive article extraction into an accessible overlay dialog. Preserves headings, links, images, and alt text while stripping forms, navigation, and sensitive fields. Supports Light/Sepia/Dark themes and zoom. See docs/READING_MODE.md. |
36
+ | KeyboardShortcutsController / shortcutsEnabled / customShortcuts | false; boolean / Record<string, string> | Discoverable shortcut cheat sheet, conflict-checked remapping, reserved browser protection (Ctrl+U, Ctrl+R), form suppression, and Link Explorer with uninformative text detection. See docs/KEYBOARD_SHORTCUTS.md. |
37
+ | ReadAloudController / readAloud / readAloudRate / readAloudPitch / readAloudVoice | false; 1.0; 1.0; null | User-initiated client-side text-to-speech read-aloud via Web Speech API (`speechSynthesis`). Sentence-level chunking, pause/resume/stop, voice selection, rate and pitch steppers, Escape dismissal, sensitive/form field exclusions, and zero network transmission. See docs/READ_ALOUD.md. |
38
+ | DictionaryController | Action dialog; no persistent preference | Accessible terminology dictionary and provider interface. Explicit user action lookup, 100% offline local static glossaries (English, Sinhala, Tamil), zero network transmission by default, truthful non-hallucinating responses, sensitive data rejection, and focus restoration. See docs/DICTIONARY.md. |
39
+ | VoiceNavigationController / voiceNavigation | false; boolean | User-initiated speech recognition navigation research prototype using native Web Speech API. Recognizes explicit commands (open, close, next/prev/first heading, scroll down/up/top/bottom, stop, help). Features 30s silence timeout, background tab auto-stop, zero audio storage, and full keyboard alternatives. See docs/VOICE_NAVIGATION.md. |
40
+ | FeatureMenu / menuConfig | MenuCustomizationConfig; customizable | Declarative per-site feature menu reordering, grouping, custom labels, suggested defaults, non-crashing safe diagnostics, and memoized stable rerenders. See docs/MENU_CUSTOMIZATION.md. |
41
+ | ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
35
42
 
36
43
  ## Accessible control primitives and UI states
37
44
 
@@ -74,3 +81,49 @@ Widget placement is now a persisted preference with pointer dragging and non-dra
74
81
  ## Verification mapping
75
82
 
76
83
  `tests/features.test.tsx`: stepper bounds, palettes, all alignment states, boolean effects, combined filters, native host restoration and dynamic routes. `tests/plugin.test.tsx`: custom lifecycle, restoration, invalid data, focus, Strict Mode, SSR, hydration, singleton enforcement. `tests/storage.test.ts`: deterministic timers, errors and schema envelopes. `tests/browser/widget.spec.ts`: actual compiled CSS, packed consumers, visibility, pointer interaction, geometry, keyboard and axe. See project status for executed results and manual gaps.
84
+
85
+ ## Development-Only Integration Diagnostics & Test Harness (A11Y-405)
86
+
87
+ The integration diagnostics suite (`runDiagnostics`, `DiagnosticsHarness`, `useDiagnostics`) performs non-invasive environment, DOM, and styling checks during development:
88
+
89
+ - **Provider & Widget Placement**: Diagnoses multiple providers and identifies ancestor containing-block traps (`filter`, `transform`, `perspective`).
90
+ - **Storage Boundaries**: Tests `localStorage` / `sessionStorage` accessibility, quotas, and sandbox restrictions with graceful in-memory fallback.
91
+ - **CSP & Style Injection**: Tests dynamic `<style>` injection and CSS custom property support against restrictive `style-src`.
92
+ - **Host CSS Conflicts**: Detects extreme host `z-index >= 2,147,483,000` and root scroll locks (`overflow: hidden` on both `html` and `body`).
93
+ - **DOM & Landmark Structure**: Scans for `<main>` landmarks, `<h1>` titles, skipped heading levels, and unlabelled content `<img>` tags (privacy-safe, no sensitive URLs or PII).
94
+ - **Boundaries**: Flags embedded `<iframe>` elements (cross-origin styling boundaries) and custom elements with `ShadowRoot`.
95
+ - **Zero Compliance Claims**: All reports carry an explicit disclaimer stating that automated diagnostics do not constitute official WCAG certification or replace manual audits.
96
+
97
+ ## Optional Privacy-Safe Feature Event Callbacks (A11Y-406)
98
+
99
+ The optional lifecycle callback (`onFeatureEvent` on `<AccessibilityPlugin>`) provides local, in-memory event notifications for host application telemetry:
100
+
101
+ - **Strictly Opt-In**: Disabled by default; zero events or network requests are emitted unless an explicit listener callback is supplied.
102
+ - **Reviewed Payloads**: Emits coarse event types (`feature-change`, `feature-reset`, `panel-toggle`, `placement-change`, `profile-apply`, `preset-apply`) with scalar values and canonical feature IDs.
103
+ - **Strict Privacy Exclusions**: Never includes page text, user text selections, form inputs, emails, user IDs, cookies, device fingerprints, or Web Speech transcripts/audio recordings.
104
+ - **Sanitized and Frozen**: All payloads are validated against an allowlist and deep-frozen (`Object.freeze`).
105
+ - **Resilient**: Exceptions thrown in consumer listeners are safely caught and silenced, ensuring application functionality is never interrupted.
106
+
107
+ ## Voice Navigation Research Prototype (A11Y-408)
108
+
109
+ The Voice Navigation Research Prototype (`VoiceNavigationController`, `createVoiceNavigationSession`) provides user-initiated speech control for page navigation:
110
+
111
+ - **Local Speech Recognition**: Leverages client platform Web Speech Recognition API with zero external network transmission.
112
+ - **Strict Privacy Guarantees**: Zero recording or audio persistence in `localStorage`, `sessionStorage`, or cookies; interim/final transcripts are purely transient in component memory.
113
+ - **Inactivity Watchdog**: Automatically shuts down listening after 30 seconds of silence to prevent open background microphones.
114
+ - **Background Tab Protection**: Automatically stops speech recognition when `document.hidden` becomes true.
115
+ - **Accessible Keyboard Alternatives**: Full set of native buttons for heading navigation and scrolling; 100% operational in unsupported browsers or upon permission denial.
116
+ - **Reduced Motion Respect**: Automatically disables smooth scrolling in favor of instant jumps when reduced motion preferences are detected.
117
+
118
+ ## Host-Content Translation Adapter Architecture (A11Y-409)
119
+
120
+ The Host-Content Translation Adapter Architecture (`TranslationController`, `translateHostContent`) provides a privacy-first, decoupled bridge for translating arbitrary host application text:
121
+
122
+ - **Decoupled from Widget Localization**: Clear separation between bundled static widget strings (`src/core/i18n/`) and host content translation.
123
+ - **Provider Interface Boundary**: Pluggable `TranslationAdapter` interface specifying data retention, residency, and privacy policies.
124
+ - **Explicit User Consent**: Strictly user-initiated; requires explicit acknowledgment via consent modal before transmitting host document text.
125
+ - **Strict Sensitive Content Exclusion**: Automatically detects and ignores form passwords, credit card/CVC fields, personal email/phone inputs, technical code blocks (`<code>`, `<pre>`), media boundaries (`<iframe>`, `<svg>`), opt-out attributes (`[translate="no"]`), hidden nodes, and the widget itself.
126
+ - **Cross-Origin & iframe Safeguard**: Strictly excludes all `<iframe>` elements to protect Same-Origin Policy (SOP) boundaries.
127
+ - **XSS & DOM Injection Prevention**: Translated text is strictly assigned via `Text.textContent`, never `innerHTML`.
128
+ - **Clean Synchronous Restoration**: Synchronous `restore()` callback resets modified text nodes back to original host strings immediately.
129
+ - **Offline Mock Translation Adapter**: `createOfflineMockTranslationAdapter` operates locally with zero network calls for testing and development.
@@ -0,0 +1,97 @@
1
+ # Keyboard Shortcuts, Collision-Checked Remapping & Link Explorer (`KeyboardShortcutsController` & `PageNavigatorController`)
2
+
3
+ The **Keyboard Shortcuts & Link Explorer** system (Issue #56, `A11Y-308`) provides discoverable shortcut cheat sheets, safe conflict-checked remapping, and comprehensive semantic link exploration across the host application.
4
+
5
+ ---
6
+
7
+ ## 1. Architectural Principles
8
+
9
+ 1. **Global Shortcuts Off by Default**:
10
+ - To respect WCAG 2.1.4 (Character Key Shortcuts) and avoid conflicting with screen reader or browser hotkeys, document-wide keyboard shortcuts are **disabled by default** (`shortcutsEnabled: false`).
11
+ - Users can explicitly opt into global shortcuts via the native toggle switch inside the shortcuts modal.
12
+ 2. **Never Hijack Browser Commands**:
13
+ - Critical browser/system keys are blacklisted from being remapped or captured:
14
+ - `Ctrl+U` / `Cmd+U` (view source)
15
+ - `Ctrl+R` / `F5` (reload)
16
+ - `Ctrl+T` (new tab), `Ctrl+W` (close tab), `Ctrl+N` (new window)
17
+ - `Ctrl+P` (print), `Ctrl+F` (find), `Ctrl+S` (save)
18
+ - `Ctrl+A`, `Ctrl+C`, `Ctrl+V`, `Ctrl+X`, `Ctrl+Z`, `Ctrl+Y`
19
+ - Developer tools (`F12`, `Ctrl+Shift+I`)
20
+ 3. **Form and Route Command Protection**:
21
+ - `isFormFieldOrEditable(event.target)` detects if keystrokes originate within `<input>`, `<textarea>`, `<select>`, `[contenteditable="true"]`, or ARIA input roles (`role="textbox"`, `role="combobox"`, `role="searchbox"`).
22
+ - Global shortcuts are immediately suppressed when typing into form fields or search inputs.
23
+ 4. **Collision Detection**:
24
+ - Proposed remappings are validated against all other active plugin shortcuts to prevent ambiguous duplicate activations.
25
+ - Enforces a modifier key requirement (`Alt+Key`, `Ctrl+Alt+Key`, `Alt+Shift+Key`) so plain alphanumeric characters do not intercept text input.
26
+ 5. **Button Alternatives**:
27
+ - Every shortcut corresponds to a persistent, accessible, focusable UI button inside the plugin panel. Keyboard users who cannot press multi-key chords have 100% equivalent access.
28
+ 6. **Semantic Link Explorer**:
29
+ - Integrated into `PageNavigatorController` alongside Headings and Landmarks.
30
+ - Identifies all `<a>` links on the page, distinguishing between internal anchors, same-origin pages, and external destinations (`target="_blank"` or cross-origin).
31
+ - Automatically flags uninformative / ambiguous link text (e.g. "click here", "read more", "more", "learn more") that fails WCAG 2.4.4 / 2.4.9.
32
+ - Provides safe scrolling and focus transfer via temporary `tabindex="-1"` without permanently mutating host DOM attributes.
33
+
34
+ ---
35
+
36
+ ## 2. Default Shortcuts Registry
37
+
38
+ | Action ID | Action Label | Category | Default Key | Can Remap |
39
+ | :-------------- | :------------------------------ | :--------- | :---------- | :---------- |
40
+ | `toggleWidget` | Toggle accessibility panel | Widget | `Alt+A` | Yes |
41
+ | `resetAll` | Reset all display settings | Widget | `Alt+R` | Yes |
42
+ | `pageNavigator` | Page Structure & Links Explorer | Navigation | `Alt+N` | Yes |
43
+ | `skipToMain` | Skip to main content landmark | Navigation | `Alt+1` | Yes |
44
+ | `readingMode` | Non-destructive Reading Mode | Reading | `Alt+M` | Yes |
45
+ | `profiles` | Accessibility Profiles | Tools | `Alt+P` | Yes |
46
+ | `presets` | Saved Presets | Tools | `Alt+S` | Yes |
47
+ | `shortcutsHelp` | Keyboard Shortcuts Help | Tools | `Alt+K` | Yes |
48
+ | `closeDialog` | Dismiss dialog or overlay | Widget | `Escape` | No (locked) |
49
+
50
+ ---
51
+
52
+ ## 3. Link Explorer Features
53
+
54
+ The **Link Explorer** tab in `PageNavigatorController` inspects all active links (`<a href>`) on the host page:
55
+
56
+ - **Filtering**: Real-time search filter matching link text or destination URL.
57
+ - **Badges**:
58
+ - `LINK`: Internal / relative same-origin link.
59
+ - `ANCHOR`: On-page hash jump (`#id`).
60
+ - `EXT`: External link (`target="_blank"` or cross-origin).
61
+ - `Ambiguous`: Visual warning badge indicating non-descriptive link text (e.g. "click here", "read more").
62
+ - **Navigation**: Click or keyboard activation safely scrolls to and focuses the link in the host DOM.
63
+
64
+ ---
65
+
66
+ ## 4. Usage
67
+
68
+ ```tsx
69
+ import {
70
+ AccessibilityPlugin,
71
+ AccessibilityButton,
72
+ AccessibilityList,
73
+ KeyboardShortcutsController,
74
+ PageNavigatorController,
75
+ } from "accessibility-plugin-react";
76
+
77
+ export function App() {
78
+ return (
79
+ <AccessibilityPlugin>
80
+ <AccessibilityButton />
81
+ <AccessibilityList>
82
+ <PageNavigatorController />
83
+ <KeyboardShortcutsController />
84
+ </AccessibilityList>
85
+ </AccessibilityPlugin>
86
+ );
87
+ }
88
+ ```
89
+
90
+ ---
91
+
92
+ ## 5. Verification Matrix
93
+
94
+ - **Unit Tests**: `tests/shortcuts.test.ts` (16 tests) + `tests/linkExplorer.test.ts` (5 tests).
95
+ - **Integration Tests**: `tests/shortcutsWidget.test.tsx` (8 tests).
96
+ - **Browser Smoke Tests**: `tests/browser/widget.spec.ts` (`A11Y-308`).
97
+ - **Translations**: Fully localized in English, Sinhala (`si-LK`), and Tamil (`ta-LK`).