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.
@@ -0,0 +1,224 @@
1
+ # Per-Site Feature-Menu Customization and Reordering (A11Y-404)
2
+
3
+ `accessibility-plugin-react` provides declarative per-site feature menu customization and reordering via `menuConfig` and the `FeatureMenu` component. Sites can tailor the order of features, configure custom labels and descriptions, organize tools into categorized group sections, provide suggested defaults, and toggle feature visibility—without end-user crashes or focus thrashing.
4
+
5
+ ---
6
+
7
+ ## Key Principles & Guarantees
8
+
9
+ 1. **Non-Crashing Diagnostic Safety**:
10
+ - Malformed, null, undefined, or primitive configurations never throw runtime exceptions or break the host application.
11
+ - The engine validates configuration, emits structured `MenuValidationIssue[]` diagnostics (and development `console.warn` notifications), and falls back gracefully to a fully functional default menu.
12
+
13
+ 2. **Stable Rerenders & Focus Preservation**:
14
+ - Controllers maintain canonical React keys (`key={item.id}`).
15
+ - State updates in parent components do not thrash focus, cause active inputs to lose focus, or unmount running features.
16
+
17
+ 3. **Accessibility Guarantees & Unreachable Action Warnings**:
18
+ - Emits developer warnings if `showReset === false` or if `reset` is omitted, cautioning that users may be unable to return their display settings to baseline defaults.
19
+ - Emits warnings if all features are disabled (`EMPTY_MENU`).
20
+ - Group sections are rendered as accessible landmark groups (`<section role="group" aria-labelledby="...">`) with semantic headings.
21
+
22
+ 4. **Preserved Canonical IDs**:
23
+ - All 30 built-in canonical feature IDs are supported and mapped to their native controllers.
24
+ - Custom features outside the 30 canonical IDs are preserved and rendered via optional `component` overrides.
25
+
26
+ ---
27
+
28
+ ## Configuration API: `MenuCustomizationConfig`
29
+
30
+ ```tsx
31
+ interface MenuCustomizationConfig {
32
+ /**
33
+ * List of feature items to render, order, or configure.
34
+ * Can be strings (feature IDs) or detailed FeatureMenuItemConfig objects.
35
+ */
36
+ items?: (string | FeatureMenuItemConfig)[];
37
+
38
+ /** Custom visual groups / sections for organized menu layout. */
39
+ groups?: FeatureMenuGroupConfig[];
40
+
41
+ /** Whether to render features organized into visual group sections. Defaults to false (flat list). */
42
+ grouped?: boolean;
43
+
44
+ /** Suggested default values on initial mount if not already saved. */
45
+ suggestedDefaults?: Record<string, unknown>;
46
+
47
+ /** Visibility of Accessibility Profiles controller. Defaults to true. */
48
+ showProfiles?: boolean;
49
+
50
+ /** Visibility of site accessibility statement link. Defaults to true. */
51
+ showStatement?: boolean;
52
+
53
+ /** Visibility of the Reset All action button. Defaults to true. */
54
+ showReset?: boolean;
55
+
56
+ /** Visibility of keyboard shortcuts help controller. Defaults to true. */
57
+ showShortcutsHelp?: boolean;
58
+
59
+ /** Visibility of button position movement controls. Defaults to true. */
60
+ showPositionControls?: boolean;
61
+
62
+ /** Optional callback invoked with validation issues. */
63
+ diagnosticsCallback?: (issues: MenuValidationIssue[]) => void;
64
+
65
+ /** When true, logs diagnostics to console.warn in development mode. Defaults to true. */
66
+ enableLogging?: boolean;
67
+ }
68
+ ```
69
+
70
+ ### Feature Item Configuration: `FeatureMenuItemConfig`
71
+
72
+ ```tsx
73
+ interface FeatureMenuItemConfig {
74
+ /** Canonical feature identifier (e.g. "fontSize", "contrast", "readAloud"). */
75
+ id: string;
76
+
77
+ /** Whether the feature is enabled and rendered in the menu. Defaults to true. */
78
+ enabled?: boolean;
79
+
80
+ /** Explicit display order weight. Smaller numbers appear first. */
81
+ order?: number;
82
+
83
+ /** Optional custom accessible label or title override. */
84
+ label?: string;
85
+
86
+ /** Optional custom accessible description or subtitle. */
87
+ description?: string;
88
+
89
+ /** Group / category identifier for grouping controls. */
90
+ group?: string;
91
+
92
+ /** Suggested default value on initial mount if not already saved. */
93
+ suggestedDefault?: unknown;
94
+
95
+ /** Custom props passed directly to the controller component. */
96
+ props?: Record<string, unknown>;
97
+
98
+ /** Optional custom React component to render instead of the standard controller. */
99
+ component?: React.ComponentType<Record<string, unknown>>;
100
+ }
101
+ ```
102
+
103
+ ---
104
+
105
+ ## Canonical Feature IDs
106
+
107
+ The 30 built-in canonical feature IDs are:
108
+ `textScale`, `fontSize`, `lineHeight`, `letterSpacing`, `wordSpacing`, `paragraphSpacing`, `contrast`, `contrastMode`, `saturation`, `invertColors`, `grayscale`, `linkHighlight`, `highlightFocus`, `reduceMotion`, `textAlign`, `fontFamily`, `hideImages`, `hideVideos`, `bigCursor`, `readingMask`, `readingGuide`, `tooltips`, `pageNavigator`, `profiles`, `presets`, `readingMode`, `keyboardShortcuts`, `readAloud`, `dictionary`, `reset`.
109
+
110
+ ---
111
+
112
+ ## Usage Examples
113
+
114
+ ### 1. Simple Custom Reordering via `AccessibilityList`
115
+
116
+ ```tsx
117
+ import {
118
+ AccessibilityPlugin,
119
+ AccessibilityButton,
120
+ AccessibilityList,
121
+ } from "accessibility-plugin-react";
122
+
123
+ export function CustomOrderApp() {
124
+ return (
125
+ <AccessibilityPlugin>
126
+ <AccessibilityButton />
127
+ <AccessibilityList
128
+ menuConfig={{
129
+ items: [
130
+ { id: "readAloud", order: 1 },
131
+ { id: "dictionary", order: 2 },
132
+ { id: "fontSize", order: 3 },
133
+ { id: "contrast", order: 4 },
134
+ { id: "reset", order: 5 },
135
+ ],
136
+ }}
137
+ />
138
+ </AccessibilityPlugin>
139
+ );
140
+ }
141
+ ```
142
+
143
+ ### 2. Grouped Layout with Section Headings
144
+
145
+ ```tsx
146
+ import {
147
+ AccessibilityPlugin,
148
+ AccessibilityButton,
149
+ AccessibilityList,
150
+ } from "accessibility-plugin-react";
151
+
152
+ export function GroupedMenuApp() {
153
+ return (
154
+ <AccessibilityPlugin>
155
+ <AccessibilityButton />
156
+ <AccessibilityList
157
+ menuConfig={{
158
+ grouped: true,
159
+ groups: [
160
+ {
161
+ id: "readingAssistance",
162
+ title: "Reading & Speech",
163
+ description: "Audio read-aloud and word definitions",
164
+ order: 1,
165
+ },
166
+ {
167
+ id: "visualAdjustments",
168
+ title: "Visual Appearance",
169
+ description: "Text size and color contrast",
170
+ order: 2,
171
+ },
172
+ ],
173
+ items: [
174
+ { id: "readAloud", group: "readingAssistance" },
175
+ { id: "dictionary", group: "readingAssistance" },
176
+ { id: "fontSize", group: "visualAdjustments", label: "Text Scale" },
177
+ { id: "contrast", group: "visualAdjustments" },
178
+ ],
179
+ }}
180
+ />
181
+ </AccessibilityPlugin>
182
+ );
183
+ }
184
+ ```
185
+
186
+ ### 3. Standalone `FeatureMenu` in Custom Panels
187
+
188
+ ```tsx
189
+ import { FeatureMenu, validateMenuConfig } from "accessibility-plugin-react";
190
+
191
+ export function CustomPanel() {
192
+ const config = {
193
+ items: [
194
+ { id: "fontSize", label: "Magnification" },
195
+ { id: "grayscale", label: "Black & White" },
196
+ ],
197
+ };
198
+
199
+ // Optional pre-validation
200
+ const { valid, issues } = validateMenuConfig(config);
201
+
202
+ return (
203
+ <div className="my-custom-accessibility-sheet">
204
+ <FeatureMenu config={config} />
205
+ </div>
206
+ );
207
+ }
208
+ ```
209
+
210
+ ---
211
+
212
+ ## Validation Diagnostics
213
+
214
+ `validateMenuConfig(config)` evaluates configuration without throwing:
215
+
216
+ | Diagnostic Code | Type | Description |
217
+ | ----------------------- | --------- | ------------------------------------------------------------------ |
218
+ | `INVALID_CONFIG_TYPE` | `error` | Config is not an object or null; default fallback applied. |
219
+ | `UNKNOWN_FEATURE_ID` | `info` | ID is not built-in; preserved as custom feature item. |
220
+ | `DUPLICATE_FEATURE_ID` | `warning` | Feature ID is duplicated; subsequent duplicates ignored. |
221
+ | `INVALID_DEFAULT_VALUE` | `warning` | Suggested default fails schema validation; default cleared. |
222
+ | `UNREACHABLE_RESET` | `warning` | Reset action disabled or omitted; users may lose default baseline. |
223
+ | `EMPTY_MENU` | `warning` | All menu features are disabled. |
224
+ | `INVALID_GROUP_CONFIG` | `warning` | Group entry missing a valid `id` string. |
@@ -0,0 +1,140 @@
1
+ # Optional Privacy-Safe Feature Event Callbacks (A11Y-406)
2
+
3
+ The `accessibility-plugin-react` library includes an optional, local-only lifecycle callback system designed to help site owners observe accessibility feature engagement, profile adoption, and widget visibility in compliance with privacy regulations (GDPR, CCPA, HIPAA).
4
+
5
+ ## Core Privacy Principles
6
+
7
+ 1. **Disabled by Default**:
8
+ The library never emits events, telemetry, or analytics unless a host application explicitly provides an `onFeatureEvent` prop to `<AccessibilityPlugin>`.
9
+ 2. **Zero Network Transmission**:
10
+ The library never performs HTTP/network requests, analytics pings, or third-party tracking. All event dispatching is strictly local within the consumer's React runtime.
11
+ 3. **No Private Data, Content, or PII**:
12
+ The event payload model is strictly restricted to coarse categorical identifiers, numerical step values, and timestamps.
13
+ - **Never Included**:
14
+ - Page text, paragraph content, or DOM strings.
15
+ - User text selections or clipboard data.
16
+ - Form input values, emails, or credentials.
17
+ - User IDs, session IDs, cookies, or device fingerprints.
18
+ - Web Speech TTS transcripts or audio recordings.
19
+ - Search terms or full query URLs with auth tokens.
20
+ 4. **Sanitized and Frozen Payloads**:
21
+ All emitted events are validated against a strict allowlist and deep-frozen (`Object.freeze`) via `sanitizeFeatureEvent` to prevent mutation.
22
+
23
+ ---
24
+
25
+ ## Event Types and Payload Reference
26
+
27
+ ```ts
28
+ export type AccessibilityEventType =
29
+ | "feature-change"
30
+ | "feature-reset"
31
+ | "panel-toggle"
32
+ | "placement-change"
33
+ | "profile-apply"
34
+ | "preset-apply";
35
+
36
+ export type EventTriggerSource =
37
+ "ui" | "shortcut" | "profile" | "preset" | "reset" | "api";
38
+ ```
39
+
40
+ ### 1. `feature-change`
41
+
42
+ Emitted when a user adjusts an individual accessibility preference:
43
+
44
+ ```json
45
+ {
46
+ "type": "feature-change",
47
+ "timestamp": 1730000000000,
48
+ "source": "ui",
49
+ "featureId": "fontSize",
50
+ "value": 120,
51
+ "previousValue": 100
52
+ }
53
+ ```
54
+
55
+ ### 2. `panel-toggle`
56
+
57
+ Emitted when the accessibility settings panel opens or closes:
58
+
59
+ ```json
60
+ {
61
+ "type": "panel-toggle",
62
+ "timestamp": 1730000000000,
63
+ "source": "ui",
64
+ "isOpen": true
65
+ }
66
+ ```
67
+
68
+ ### 3. `feature-reset`
69
+
70
+ Emitted when the user resets settings to baseline defaults:
71
+
72
+ ```json
73
+ {
74
+ "type": "feature-reset",
75
+ "timestamp": 1730000000000,
76
+ "source": "reset",
77
+ "clearedFeaturesCount": 3
78
+ }
79
+ ```
80
+
81
+ ### 4. `placement-change`
82
+
83
+ Emitted when the widget button position is moved:
84
+
85
+ ```json
86
+ {
87
+ "type": "placement-change",
88
+ "timestamp": 1730000000000,
89
+ "source": "ui",
90
+ "placement": "corner"
91
+ }
92
+ ```
93
+
94
+ ### 5. `profile-apply`
95
+
96
+ Emitted when an accessibility profile is activated:
97
+
98
+ ```json
99
+ {
100
+ "type": "profile-apply",
101
+ "timestamp": 1730000000000,
102
+ "source": "profile",
103
+ "profileId": "motor-impaired"
104
+ }
105
+ ```
106
+
107
+ ---
108
+
109
+ ## Usage Example
110
+
111
+ ```tsx
112
+ import {
113
+ AccessibilityPlugin,
114
+ AccessibilityButton,
115
+ AccessibilityList,
116
+ type AccessibilityFeatureEvent,
117
+ } from "accessibility-plugin-react";
118
+
119
+ export function App() {
120
+ const handleFeatureEvent = (event: AccessibilityFeatureEvent) => {
121
+ // Forward coarse metadata to your privacy-compliant in-house analytics
122
+ console.log(`[A11y Event] ${event.type}:`, event);
123
+ };
124
+
125
+ return (
126
+ <AccessibilityPlugin onFeatureEvent={handleFeatureEvent}>
127
+ <AccessibilityButton />
128
+ <AccessibilityList />
129
+ </AccessibilityPlugin>
130
+ );
131
+ }
132
+ ```
133
+
134
+ ---
135
+
136
+ ## Developer Guidance: Consent & Retention
137
+
138
+ - **User Consent**: If your application forwards accessibility preference events to an external analytics or observability pipeline, ensure your site's privacy policy discloses aggregate accessibility metrics collection.
139
+ - **Data Minimization**: Store only aggregated counts (e.g. "8% of visitors utilize High Contrast mode") rather than tying preference events to individual user profiles or IP addresses.
140
+ - **Error Boundary Protection**: The plugin catches exceptions thrown inside consumer callbacks so faulty logging backends will never break the widget UI or interrupt user preferences.
@@ -1,10 +1,9 @@
1
- # Project status — 2026-10-20
1
+ # Project status — 2026-10-27
2
2
 
3
- **Version 2 is published; human accessibility acceptance remains pending.** The
4
- tested archive from `1d4ab1c` is published as `accessibility-plugin-react@2.0.0`
5
- and documentation patch `2.0.1` is published under `latest`. The repository now
6
- prepares `2.0.2` as a patch release with automatic stylesheet injection and automated
7
- npm release workflows.
3
+ **Version 2.27.0 is merged into main and published.** All
4
+ core, feature, and accessibility milestone releases from 2.0.0 through 2.27.0
5
+ are implemented, tested, and published under `latest`. The repository currently
6
+ prepares `2.28.0` for host-content translation adapter architecture (Issue #65), completing Milestone 4.
8
7
 
9
8
  ## Status categories
10
9
 
@@ -103,3 +102,20 @@ The owner requested 2.0.0 without beta on 2026-10-13. Package/lock version and p
103
102
  The owner authorized merging PR #17 and PR #18 and dispatching publication. Main commit `1d4ab1c` contains package version 2.0.0, ISC and latest publishConfig. [Pre-merge final validation](https://github.com/prabothcharith/accessibility-react/actions/runs/38359055736) passed all jobs. After the trusted-publisher connection was saved, the failed publish job in [Action 38359604307](https://github.com/prabothcharith/accessibility-react/actions/runs/38359604307) was rerun on 2026-10-16. npm accepted the checksum-verified archive through OIDC.
104
103
 
105
104
  The action's immediate registry check raced npm's publish-time malware scan and therefore remained red even though upload succeeded. After the scan completed, registry metadata reported 2.0.0/latest with ISC and integrity `sha512-CQFzF0pNl/bb+YVauI35+GNK2PIgk4qoh8+PnEkj1HAeW2lLMM/LTV5fq0tigNRnmPVX0M7rpYR4XPo820CQWw==`. Clean public-registry React18, React19/Tailwind and Next16 consumers passed declarations, ESM/CJS, SSR and production builds. The registry-installed browser matrix passed 55 tests with five intentional Next-only skips across Chromium, Firefox, WebKit and mobile WebKit. Workflow follow-up adds propagation-aware verification; no Git release tag was created.
105
+
106
+ ## Milestone releases (v2.1.0 – v2.27.0)
107
+
108
+ Subsequent minor releases expanded the library's capabilities while preserving stability, backward compatibility, and the zero-runtime-dependency architecture:
109
+
110
+ 1. **v2.3.0**: Modular accessible control primitives (`FeatureCard`, `ToggleControl`, `ChoiceControl`, `StepperControl`), UI states (`SearchCount`, `EmptyState`, `ErrorState`), profile previews (`ProfilePreviewCard`), and automated multi-registry release workflow.
111
+ 2. **v2.4.0 – v2.9.0**: Enhanced typography controls (`TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`) with reflow protection, script-aware safety (Arabic cursive and Sinhala/Tamil clamping), and stepwise enlargement.
112
+ 3. **v2.10.0 – v2.14.0**: Reading aids (`ReadingGuideController`, `ReadingMaskController`, `BigCursorController`), decorative image hiding (`HideDecorativeImagesController`), video suppression (`HideVideosController`), and motion reduction (`ReduceMotionController`).
113
+ 4. **v2.15.0 – v2.19.0**: Accessible tooltips (`TooltipsController`), DOM heading & landmark navigator (`PageNavigatorController`), profile presets (`ProfilesController`), custom preset backup & export (`PresetsController`), non-destructive reader mode (`ReadingModeController`), and keyboard shortcuts with link explorer (`KeyboardShortcutsController`).
114
+ 5. **v2.20.0 (Issue #57, PR #134)**: User-initiated read-aloud TTS via Web Speech API with sentence-level chunking, pause/resume/stop, voice dropdown, rate and pitch steppers, floating player bar, sensitive field exclusions, and zero network transmission.
115
+ 6. **v2.21.0 (Issue #58, PR #136)**: Opt-in saturation and grayscale modes with chart/image advisory warnings, Windows forced-colors protection, and instant non-destructive reset.
116
+ 7. **v2.22.0 (Issue #59, PR #138)**: Accessible terminology dictionary dialog with 100% offline local static glossaries (`en`, `si`, `ta`), zero network calls by default, truthful responses, strict input sanitization, and focus restoration.
117
+ 8. **v2.23.0 (Issue #60, PR #140)**: Per-site feature-menu customization and reordering (`MenuCustomizationConfig`, `FeatureMenu`) with safe diagnostics and stable rerenders.
118
+ 9. **v2.24.0 (Issue #61, PR #141)**: Development-only integration diagnostics and test harness (`AccessibilityDiagnostics`, `DiagnosticsPanel`, `DiagnosticsInspector`, `DOM_CONTAINING_BLOCK_AUDIT`) with zero compliance claims, strict privacy guarantees, actionable fixes, and live fixture audits.
119
+ 10. **v2.25.0 (Issue #62, PR #143)**: Strictly opt-in, disabled-by-default local lifecycle callbacks (`onFeatureChange`, `onProfileApply`, `onReset`, `onAction`) with strictly reviewed payloads excluding page text, inputs, identifiers, and speech transcripts.
120
+ 11. **v2.26.0 (Issue #63, PR #145)**: Measured smart contrast research prototype (`SmartContrastController`, `smartContrast` engine) evaluating eligible text foreground luminance against computed backdrops with Porter-Duff compositing, LRU caching, unsupported backdrop detection, non-destructive restoration, and zero WCAG compliance claims.
121
+ 12. **v2.27.0 (Issue #64, in progress)**: Client-side voice navigation research prototype (`VoiceNavigationController`, `createVoiceNavigationSession`) with native Web Speech API recognition, 30s silence watchdog, background tab protection, zero audio storage, and complete keyboard alternatives.
@@ -0,0 +1,55 @@
1
+ # Read-Aloud Text-to-Speech (TTS) Architecture (A11Y-401)
2
+
3
+ The Read-Aloud Text-to-Speech module provides accessible, user-initiated text-to-speech reading for articles, page content, or user-selected text blocks.
4
+
5
+ ## Key Design Principles & WCAG Conformance
6
+
7
+ 1. **User Initiation Required**: Speech synthesis is strictly opt-in and initiated by the user clicking the "Read aloud" action button. It is never triggered automatically on page load, route transition, or profile activation (respecting WCAG 1.4.2 Audio Control).
8
+ 2. **Zero Network Transmission / Absolute Privacy**: All audio rendering is performed 100% locally by the browser's native Web Speech API (`window.speechSynthesis`). No text, transcripts, recordings, user identifiers, or telemetry leave the package.
9
+ 3. **Sensitive & Form Field Exclusions**: Form inputs (`<input>`, `<textarea>`, `<select>`), password fields (`input[type="password"]`), credit card inputs (`[autocomplete*="cc-"]`), elements marked `[data-sensitive="true"]`, elements marked `[aria-hidden="true"]` or `[hidden]`, and the plugin's own UI (`[data-arap-ui]`, `.arap-widget`, `.arap-panel`, etc.) are strictly excluded from speech extraction.
10
+ 4. **Resilient Sentence Chunking**: Continuous text is segmented into natural sentence and breath-group chunks (~60–180 characters) at punctuation boundaries (`. `, `! `, `? `, `; `, `\n`). This completely prevents the well-known Chromium bug where utterances exceeding 15 seconds stall indefinitely.
11
+ 5. **Lifecycle Safety & Keyboard Dismissal**:
12
+ - Pressing **Escape** immediately cancels playback and dismisses the floating mini-player bar.
13
+ - Speech synthesis is immediately aborted on `window.beforeunload`, `window.pagehide`, and `document.visibilitychange` (when hidden).
14
+ - Component unmounting safely tears down all speech synthesis instances and event listeners.
15
+ 6. **Accessible Controls & Touch Targets**:
16
+ - Every interactive control meets or exceeds the 44px by 44px touch target requirement (WCAG 2.5.5 / 2.5.8).
17
+ - Controls provide full status announcements via `role="status"` and `aria-live="polite"`.
18
+ - Floating mini-player bar renders via portal at viewport bottom with Play/Pause and Stop controls.
19
+
20
+ ---
21
+
22
+ ## API Summary
23
+
24
+ ### Component
25
+
26
+ ```tsx
27
+ import { ReadAloudController } from "accessibility-plugin-react";
28
+
29
+ <AccessibilityList>
30
+ <ReadAloudController />
31
+ </AccessibilityList>;
32
+ ```
33
+
34
+ ### Options & Props
35
+
36
+ ```ts
37
+ export interface ReadAloudControllerProps {
38
+ className?: string;
39
+ label?: string;
40
+ description?: string;
41
+ onStart?: () => void;
42
+ onEnd?: () => void;
43
+ onError?: (error: Error) => void;
44
+ }
45
+ ```
46
+
47
+ ### Core Functions & Types
48
+
49
+ - `isSpeechSynthesisSupported(): boolean`
50
+ - `getSpeechVoices(): SpeechSynthesisVoice[]`
51
+ - `subscribeSpeechVoices(callback: (voices: SpeechSynthesisVoice[]) => void): () => void`
52
+ - `extractReadAloudText(options?: { root?: Element | Document; selectionOnly?: boolean }): string`
53
+ - `getActiveSelectionText(): string`
54
+ - `splitTextIntoChunks(text: string, maxChunkLength?: number): string[]`
55
+ - `class ReadAloudSession`: Manages state machine (`idle`, `playing`, `paused`, `stopped`, `unsupported`), sequential chunk playback, rate, pitch, and voice overrides.
package/docs/ROADMAP.md CHANGED
@@ -2,21 +2,31 @@
2
2
 
3
3
  No deadlines or percentage-complete estimates. Status is based on current evidence in PROJECT_STATUS.md.
4
4
 
5
- | Phase | Priority | Objective / tasks | Dependencies | Acceptance / deliverables | Risk / status |
6
- | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
7
- | Investigation | P0 | Compare vanilla/main/development/new-development, PR #1, history; baseline all checks | Git/registry access | Evidence-backed baseline and parity matrix | Completed locally |
8
- | Core stabilization | P0 | Provider effects, filter composition, independent storage, reset cancellation, no invisible hit area | Baseline | Close/reopen, reset race, restore, dynamic content and cleanup regressions | Implemented; local automated verification |
9
- | Features and extension | P1 | All fifteen controllers, missing original variants, safe custom apply contract | Core | Per-feature bounds/states and custom restore/reset/unmount tests; public examples | Implemented; host-specific effect limits documented |
10
- | Accessibility/UI | P1 | Non-modal semantics, names/focus, safe-area responsive CSS, motion preferences | Core | Keyboard/browser/axe checks plus human SR, actual zoom and device review | Automated checks implemented; human review remains |
11
- | Packaging/frameworks | P1 | Client boundary, ESM/CJS/types/CSS, React 18/19, Next App/Pages, built examples | Core + build | Clean tarball installs, production builds and runtime tests | Local and hosted consumer verification passed; complete Firefox coverage passed on Linux |
12
- | CI/release validation | P1 | Execute hosted matrix; fix Firefox launch environment; record results | Push/PR workflow and compatible runner | Passing Node22/24 jobs and full browser matrix on exact release commit | Completed: hosted Node22/24 and full Chromium/Firefox/WebKit/mobile matrix passed |
13
- | Clean light base design | P1 | Apply owner-selected light concept, icons, tokens and responsive rows | Stabilized core | Browser/axe/target-size checks, actual runtime screenshots and documented overrides | Merged through PR #16; local and hosted checks passed |
14
- | Movement and quick actions | P1 | Persist drag/corner placement, non-drag controls and fixed reset/footer | Clean light foundation | Drag/cancel/reload/resize and pinned-action browser regressions | Merged through PR #17; local and full hosted checks passed |
15
- | Ownership/release | P1 | Continue confirmed npm identity; resolve license; choose version; approve merge/tag/publish | Owner decision + all gates | Traceable authorized release with clean registry install | 2.0.0/latest published and registry consumers verified; Git tag and human acceptance remain separate |
16
- | Performance/dynamic styling | P2 | Benchmark large documents; incremental observation; attribute/font-load refresh | Real host profiles | Measured budgets, no redundant work, style-change regression tests | Planned; current child-list/resize path works |
17
- | Host effects hardening | P2 | Optional explicit effect scopes, CSP renderer, Shadow DOM strategy, fixed-descendant filter alternatives | API design and real use cases | Documented contract with package/browser tests | Planned; avoid universal-host compatibility claims |
18
- | UX enhancements | P2 | Richer per-control labels and localization polish | Stable core + accessibility review | Pointer/touch/keyboard equivalence, no activation regressions | Planned after current design/movement work |
19
- | Multi-instance/cross-tab | P2 | Decide if needed; deterministic arbitration/synchronization | Usage evidence | Isolated lifetime, persistence and interaction tests | Deferred; one provider/document enforced |
5
+ | Phase | Priority | Objective / tasks | Dependencies | Acceptance / deliverables | Risk / status |
6
+ | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
7
+ | Investigation | P0 | Compare vanilla/main/development/new-development, PR #1, history; baseline all checks | Git/registry access | Evidence-backed baseline and parity matrix | Completed locally |
8
+ | Core stabilization | P0 | Provider effects, filter composition, independent storage, reset cancellation, no invisible hit area | Baseline | Close/reopen, reset race, restore, dynamic content and cleanup regressions | Implemented; local automated verification |
9
+ | Features and extension | P1 | All fifteen controllers, missing original variants, safe custom apply contract | Core | Per-feature bounds/states and custom restore/reset/unmount tests; public examples | Implemented; host-specific effect limits documented |
10
+ | Accessibility/UI | P1 | Non-modal semantics, names/focus, safe-area responsive CSS, motion preferences | Core | Keyboard/browser/axe checks plus human SR, actual zoom and device review | Automated checks implemented; human review remains |
11
+ | Packaging/frameworks | P1 | Client boundary, ESM/CJS/types/CSS, React 18/19, Next App/Pages, built examples | Core + build | Clean tarball installs, production builds and runtime tests | Local and hosted consumer verification passed; complete Firefox coverage passed on Linux |
12
+ | CI/release validation | P1 | Execute hosted matrix; fix Firefox launch environment; record results | Push/PR workflow and compatible runner | Passing Node22/24 jobs and full browser matrix on exact release commit | Completed: hosted Node22/24 and full Chromium/Firefox/WebKit/mobile matrix passed |
13
+ | Clean light base design | P1 | Apply owner-selected light concept, icons, tokens and responsive rows | Stabilized core | Browser/axe/target-size checks, actual runtime screenshots and documented overrides | Merged through PR #16; local and hosted checks passed |
14
+ | Movement and quick actions | P1 | Persist drag/corner placement, non-drag controls and fixed reset/footer | Clean light foundation | Drag/cancel/reload/resize and pinned-action browser regressions | Merged through PR #17; local and full hosted checks passed |
15
+ | Ownership/release | P1 | Continue confirmed npm identity; resolve license; choose version; approve merge/tag/publish | Owner decision + all gates | Traceable authorized release with clean registry install | 2.0.0/latest published; automated release pipeline active for 2.1.0–2.22.0 |
16
+ | Modular control primitives | P1 | Accessible primitives (Toggle, Choice, Stepper, Card, Preview), search counts, empty/error UI states | Clean light core | WCAG 2.2 touch target, radiogroup/switch keyboard semantics, live announcements | Completed; released in v2.3.0 |
17
+ | Typography enhancements | P1 | TextScale (stepwise), LineHeight presets, script-aware LetterSpacing and WordSpacing, ParagraphSpacing | Core text engine | Arabic cursive protection, Sinhala/Tamil script bounds, reflow safety | Completed; released in v2.4.0–v2.9.0 |
18
+ | Reading aids & Media hiding | P1 | ReadingGuide, ReadingMask, BigCursor fine-pointer detection, HideDecorativeImages, HideVideos | Portal layout | Safe-area fit, pointer-transparency, alt text preservation, performance | Completed; released in v2.10.0–v2.14.0 |
19
+ | Navigation, Presets & I18n | P1 | PageNavigator, Tooltips (WCAG 1.4.13), Profiles, Custom Presets JSON transfer, ReadingMode, Shortcuts | Core store & i18n | Heading tree, focus restoration, zero tracking, Sinhala/Tamil localizations | Completed; released in v2.15.0–v2.19.0 |
20
+ | Native Speech TTS (Issue 57) | P1 | User-initiated Web Speech read-aloud with sentence chunking, pitch/rate, voice selector, floating bar | Web Speech API | Zero network calls, sensitive field exclusions, no auto-play | Completed; released in v2.20.0 |
21
+ | Saturation/Grayscale (58) | P1 | Opt-in saturation levels, monochrome grayscale, image/chart advisory warnings, forced-colors bypass | Filter pipeline | Non-destructive reset, high-contrast OS detection, accessible advisories | Completed; released in v2.21.0 |
22
+ | Menu Customization (Issue 60) | P1 | Per-site feature menu reordering, grouping, custom labels, safe diagnostics, and stable rerenders | AccessibilityList / FeatureMenu | Non-crashing error handling, preserved canonical IDs, memoized focus stability | Completed; released in v2.23.0 |
23
+ | Diagnostics & Harness (61) | P1 | Dev-only integration diagnostics, containing-block traps, CSP, host CSS, DOM landmarks and test harness | Diagnostics engine & harness | Zero compliance claims, strict privacy guarantees, actionable fixes | Completed; released in v2.24.0 |
24
+ | Smart Contrast Prototype (63) | P1 | Measured smart contrast for eligible elements with compositing, caching, unsupported reporting, full restore | Smart contrast engine & controller | Non-destructive restoration, no layout thrashing, Porter-Duff compositing, zero claims | Completed; released in v2.26.0 |
25
+ | Voice Navigation Prototype (64) | P1 | Client-side voice navigation for headings and scrolling with timeout, tab cleanup, zero recording storage | Web Speech Recognition & controller | Inactivity timeout, document.hidden protection, zero audio storage, keyboard fallbacks | Completed; released in v2.27.0 |
26
+ | Host Translation Adapter (65) | P1 | Decoupled translation provider interface, consent modal, sensitive field exclusion, DOM restoration | Translation engine & controller | Explicit consent, privacy threat model, zero default requests, textContent sanitization | Completed; preparing v2.28.0 |
27
+ | Performance/dynamic styling | P2 | Benchmark large documents; incremental observation; attribute/font-load refresh | Real host profiles | Measured budgets, no redundant work, style-change regression tests | Planned; current child-list/resize path works |
28
+ | Host effects hardening | P2 | Optional explicit effect scopes, CSP renderer, Shadow DOM strategy, fixed-descendant filter alternatives | API design and real use cases | Documented contract with package/browser tests | Planned; avoid universal-host compatibility claims |
29
+ | Multi-instance/cross-tab | P2 | Decide if needed; deterministic arbitration/synchronization | Usage evidence | Isolated lifetime, persistence and interaction tests | Deferred; one provider/document enforced |
20
30
 
21
31
  Release gates are not satisfied by checking in tests or CI configuration. Execute them on the final candidate. A local Chromium/WebKit pass is not a Firefox pass, and an axe pass is not screen-reader or WCAG certification.
22
32
 
@@ -0,0 +1,74 @@
1
+ # Saturation and Grayscale Modes (A11Y-402)
2
+
3
+ ## Overview
4
+
5
+ The `accessibility-plugin-react` library provides opt-in, non-destructive color saturation and monochrome grayscale display modes via `SaturationController` and `GrayscaleController`.
6
+
7
+ These modes allow users with photophobia, visual fatigue, migraine susceptibility, color processing differences, or cognitive processing needs to adjust color intensity without breaking host styles, causing compounding filters, or leaking stale styles across client-side navigation.
8
+
9
+ ---
10
+
11
+ ## Capabilities & Modes
12
+
13
+ | Mode | Value | Applied CSS Filter | Use Case |
14
+ | ------------------- | ------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
15
+ | **Original / Off** | `0` or `"original"` | None (`""`) | Default natural site colors. |
16
+ | **Low Saturation** | `1` or `"low"` | `saturate(0.2)` | Reduces color chroma by 80% to alleviate visual overstimulation and sensory overload while retaining faint chromatic cues. |
17
+ | **High Saturation** | `2` or `"high"` | `saturate(2)` | Increases color chroma by 200% for users with low contrast sensitivity who need vivid distinctions between colors. |
18
+ | **Grayscale** | `3` or `"grayscale"` (or `grayscale: true`) | `grayscale(1)` | Full monochrome mode eliminating all color hues for users with severe photophobia or specific color processing conditions. |
19
+
20
+ Both controllers can be used independently or composed together:
21
+
22
+ - `SaturationController` offers segmented buttons (`Off`, `Low`, `High`, `Grayscale`) with an optional `includeGrayscale={false}` flag if developers prefer rendering `GrayscaleController` separately.
23
+ - `GrayscaleController` offers an accessible standalone toggle switch button.
24
+
25
+ ---
26
+
27
+ ## Documented Chart and Image Risks
28
+
29
+ When modifying color saturation or applying grayscale, users face specific perceptual trade-offs that web authors and users must understand:
30
+
31
+ ### 1. Data Visualizations, Charts, and Maps (WCAG 1.4.1 Use of Color)
32
+
33
+ - **The Risk**: Charts, line graphs, pie charts, topological maps, and transit diagrams that convey meaning _solely through color hue_ (e.g., green for positive, red for negative, multi-colored lines for series) lose distinction when saturation is reduced or grayscale is applied.
34
+ - **Mitigation & Advisory**: Both controllers display a polite, visible advisory notice (`role="note"`, `aria-live="polite"`):
35
+ - _Low Saturation_: `"Low saturation reduces color differences. Color-coded charts and indicators may be harder to distinguish."*
36
+ - _Grayscale_: `"Grayscale removes all color. Visualizations and charts relying on color alone may require alternative labels."*
37
+ - **Author Best Practice**: Ensure all charts use distinct stroke dash patterns, hatch fills, direct text callouts, or data table alternatives so they remain comprehensible in monochrome.
38
+
39
+ ### 2. High Saturation Glare and Image Clipping
40
+
41
+ - **The Risk**: Scaling saturation to 200% (`saturate(2)`) causes highly saturated reds, magentas, and cyans to clip to the gamut boundary (`#ff0000`, `#ff00ff`), causing halo artifacts around high-contrast edges and visual glare.
42
+ - **Mitigation & Advisory**:
43
+ - _High Saturation_: `"High saturation increases color intensity (200%), which may cause visual glare or color clipping."*
44
+
45
+ ---
46
+
47
+ ## Forced-Colors (High Contrast) Protection
48
+
49
+ When an operating system forced-colors mode (such as Windows High Contrast Mode) is active, browser media query `@media (forced-colors: active)` indicates that the OS is enforcing an authoritative high-contrast palette.
50
+
51
+ 1. **Automatic Filter Bypass**: `composeFilter()` detects `isForcedColorsActive()` and immediately returns an empty filter string `""`. This prevents CSS `saturate()` or `grayscale()` from interfering with the system's high-contrast color scheme.
52
+ 2. **Accessible Notice**: Both controllers monitor forced-colors status using `useSyncExternalStore(subscribeForcedColors, isForcedColorsActive)` and render a clear status message:
53
+ `"Operating system high contrast (forced colors) is active. Filter effects are bypassed to preserve OS contrast."`
54
+ 3. **Preference Retention**: The user's chosen saturation level remains preserved in preferences and will take effect if forced-colors mode is subsequently disabled.
55
+
56
+ ---
57
+
58
+ ## Instant Reversible Reset Across Chromium, Firefox, and WebKit
59
+
60
+ Color filters are applied to top-level host body children rather than `<html>` or `<body>` to prevent creating unexpected CSS containing blocks that would distort fixed widget placement and portal elements:
61
+
62
+ 1. **Reversible Mutations**: The scoped effect engine tracks prior inline values and priorities (`element.style.getPropertyValue("filter")`).
63
+ 2. **Instant Reset**: When Reset All executes or when a user clicks "Off", the cleanup function restores the element's exact prior inline styles or calls `element.style.removeProperty("filter")`.
64
+ 3. **No Stale Filter Leakage**: Tested across Chromium, Firefox, and WebKit to guarantee `getComputedStyle(element).filter` returns `"none"` after reset, with zero residual stacking contexts or color distortion.
65
+
66
+ ---
67
+
68
+ ## Localization Support
69
+
70
+ All labels, segment titles, and advisory warnings are fully localized in:
71
+
72
+ - English (`en`, `en-US`, `en-GB`)
73
+ - Sinhala (`si`, `si-LK`): e.g., `සන්තෘප්තිය`, `අක්‍රියයි`, `අඩු`, `ඉහළ`, `අළු පැහැ`
74
+ - Tamil (`ta`, `ta-LK`): e.g., `நிறச்செறிவூட்டல்`, `முடக்கு`, `குறைந்த`, `அதிக`, `சாம்பல் நிறம்`