accessibility-plugin-react 2.10.0 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/style.css CHANGED
@@ -1093,3 +1093,85 @@
1093
1093
  border-color: #fde68a;
1094
1094
  color: #92400e;
1095
1095
  }
1096
+
1097
+ /* Reading aids and overlays */
1098
+ .arap-reading-mask {
1099
+ position: fixed !important;
1100
+ left: 0 !important;
1101
+ right: 0 !important;
1102
+ pointer-events: none !important;
1103
+ user-select: none !important;
1104
+ -webkit-user-select: none !important;
1105
+ touch-action: none !important;
1106
+ z-index: 2147482999 !important;
1107
+ }
1108
+
1109
+ .arap-reading-guide {
1110
+ position: fixed !important;
1111
+ left: 0 !important;
1112
+ right: 0 !important;
1113
+ pointer-events: none !important;
1114
+ user-select: none !important;
1115
+ -webkit-user-select: none !important;
1116
+ touch-action: none !important;
1117
+ z-index: 2147482999 !important;
1118
+ }
1119
+
1120
+ .arap-feature-expandable {
1121
+ flex-direction: column !important;
1122
+ align-items: stretch !important;
1123
+ }
1124
+
1125
+ /* Accessible Tooltips (A11Y-302) */
1126
+ .arap-accessible-tooltip {
1127
+ position: fixed !important;
1128
+ z-index: 2147483646 !important;
1129
+ max-width: 320px !important;
1130
+ min-width: 48px !important;
1131
+ box-sizing: border-box !important;
1132
+ padding: 6px 12px !important;
1133
+ background: #0f172a !important;
1134
+ color: #ffffff !important;
1135
+ font-family:
1136
+ -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
1137
+ Arial, sans-serif !important;
1138
+ font-size: 13px !important;
1139
+ line-height: 1.4 !important;
1140
+ font-weight: 500 !important;
1141
+ border-radius: 6px !important;
1142
+ box-shadow:
1143
+ 0 4px 14px rgba(0, 0, 0, 0.25),
1144
+ 0 0 0 1px rgba(255, 255, 255, 0.15) !important;
1145
+ pointer-events: auto !important;
1146
+ word-break: break-word !important;
1147
+ white-space: normal !important;
1148
+ opacity: 0 !important;
1149
+ visibility: hidden !important;
1150
+ transition:
1151
+ opacity 120ms ease,
1152
+ transform 120ms ease !important;
1153
+ transform: translateY(2px) !important;
1154
+ }
1155
+
1156
+ .arap-accessible-tooltip[data-visible="true"] {
1157
+ opacity: 1 !important;
1158
+ visibility: visible !important;
1159
+ transform: translateY(0) !important;
1160
+ }
1161
+
1162
+ .arap-accessible-tooltip[data-placement="top"] {
1163
+ transform: translateY(-2px) !important;
1164
+ }
1165
+
1166
+ .arap-accessible-tooltip[data-placement="top"][data-visible="true"] {
1167
+ transform: translateY(0) !important;
1168
+ }
1169
+
1170
+ @media (forced-colors: active) {
1171
+ .arap-accessible-tooltip {
1172
+ background: Canvas !important;
1173
+ color: CanvasText !important;
1174
+ border: 2px solid Highlight !important;
1175
+ box-shadow: none !important;
1176
+ }
1177
+ }
package/docs/API.md CHANGED
@@ -48,11 +48,11 @@ Definitions/defaults are immutable for the provider lifetime; the first register
48
48
 
49
49
  `FeatureRegistration` is `FeatureOptions<unknown>` plus `defaultValue: unknown`. Use the generic hook instead of manually casting callbacks. Legacy `registerReset(key, fn)` / `unregisterReset(key)` remain available; callbacks run before global state is cleared. They are not the primary effect lifecycle API. Callback owners must unregister their callback on teardown.
50
50
 
51
- Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions<T>`, `FeatureRegistration`, `ToggleControlProps`, `ChoiceControlProps`, `ChoiceOption<T>`, `ChoiceGroup<T>`, `StepperControlProps`, `FeatureCardProps`, `FeatureStatus`, `SearchCountProps`, `EmptyStateProps`, `ErrorStateProps`, `ProfilePreviewCardProps`, `FontSizeControllerProps`, `TextScaleControllerProps`, `TextScaleStep`, `FontFamilyPreset`, `ContrastModeValue`, `ContrastPalette`, `LineHeightControllerProps`, `LetterSpacingControllerProps`, `WordSpacingControllerProps`, `ParagraphSpacingControllerProps`, `ScriptSpacingConstraints`, `SkipToMainLinkProps`, `HideImagesControllerProps`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`.
51
+ Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions<T>`, `FeatureRegistration`, `ToggleControlProps`, `ChoiceControlProps`, `ChoiceOption<T>`, `ChoiceGroup<T>`, `StepperControlProps`, `FeatureCardProps`, `FeatureStatus`, `SearchCountProps`, `EmptyStateProps`, `ErrorStateProps`, `ProfilePreviewCardProps`, `FontSizeControllerProps`, `TextScaleControllerProps`, `TextScaleStep`, `FontFamilyPreset`, `ContrastModeValue`, `ContrastPalette`, `LineHeightControllerProps`, `LetterSpacingControllerProps`, `WordSpacingControllerProps`, `ParagraphSpacingControllerProps`, `ScriptSpacingConstraints`, `SkipToMainLinkProps`, `HideImagesControllerProps`, `BigCursorControllerProps`, `ReadingMaskControllerProps`, `ReadingGuideControllerProps`, `TooltipsControllerProps`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`.
52
52
 
53
- Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`, `FontFamilyController`, `TextAlignController`, `ContrastController`, `ContrastModeController`, `LinkHighlightController`, `HighlightFocusController`, `FocusHighlightController`, `ReduceMotionController`, `HideImagesController`, `HideDecorativeImagesController`, `SkipToMainLink`.
53
+ Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`, `FontFamilyController`, `TextAlignController`, `ContrastController`, `ContrastModeController`, `LinkHighlightController`, `HighlightFocusController`, `FocusHighlightController`, `ReduceMotionController`, `HideImagesController`, `HideDecorativeImagesController`, `BigCursorController`, `ReadingMaskController`, `ReadingGuideController`, `TooltipsController`, `AccessibleTooltipsController`, `SkipToMainLink`.
54
54
 
55
- Exported typography, contrast, and reflow utilities: `TEXT_SCALE_STEPS`, `TEXT_SCALE_PROTECTED_SELECTOR`, `isProtectedFromTextScale`, `LINE_HEIGHT_STEPS`, `LINE_HEIGHT_RATIOS`, `TEXT_SPACING_EXCLUDED_SELECTOR`, `isProtectedFromTextSpacing`, `getScriptSpacingConstraints`, `FONT_FAMILY_PRESETS`, `LEGIBLE_FONT_STACK`, `DYSLEXIA_FONT_STACK`, `FONT_FAMILY_PROTECTED_SELECTOR`, `isProtectedFromFontFamily`, `TEXT_ALIGN_BLOCK_SELECTOR`, `isProtectedFromTextAlign`, `CONTRAST_MODES`, `isForcedColorsActive`, `subscribeForcedColors`, `isReducedMotionActive`, `subscribeReducedMotion`, `isEligibleDecorativeImage`, `isFunctionalOrMeaningfulImage`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`.
55
+ Exported typography, contrast, reading aids, tooltips, and reflow utilities: `TEXT_SCALE_STEPS`, `TEXT_SCALE_PROTECTED_SELECTOR`, `isProtectedFromTextScale`, `LINE_HEIGHT_STEPS`, `LINE_HEIGHT_RATIOS`, `TEXT_SPACING_EXCLUDED_SELECTOR`, `isProtectedFromTextSpacing`, `getScriptSpacingConstraints`, `FONT_FAMILY_PRESETS`, `LEGIBLE_FONT_STACK`, `DYSLEXIA_FONT_STACK`, `FONT_FAMILY_PROTECTED_SELECTOR`, `isProtectedFromFontFamily`, `TEXT_ALIGN_BLOCK_SELECTOR`, `isProtectedFromTextAlign`, `CONTRAST_MODES`, `isForcedColorsActive`, `subscribeForcedColors`, `isReducedMotionActive`, `subscribeReducedMotion`, `isEligibleDecorativeImage`, `isFunctionalOrMeaningfulImage`, `hasFinePointer`, `subscribeFinePointer`, `nudgeReadingAid`, `DEFAULT_READING_MASK_HEIGHT`, `MIN_READING_MASK_HEIGHT`, `MAX_READING_MASK_HEIGHT`, `READING_MASK_HEIGHT_PRESETS`, `getAuthoredDescription`, `positionTooltip`, `enableAccessibleTooltips`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`.
56
56
 
57
57
  Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
58
58
 
@@ -56,7 +56,7 @@ completed. Closing a child issue does not replace the milestone exit review.
56
56
  - [ ] [Master feature-release program #21](https://github.com/prabothcharith/accessibility-react/issues/21) — Coordinate the complete feature-release program, enforce scope and guardrails, and accept milestone evidence without treating planned work as shipped.
57
57
  - [ ] [M0 — Repository audit and compatibility safety net #22](https://github.com/prabothcharith/accessibility-react/issues/22) — Establish the real repository/package baseline, protect compatibility, and finish the M0 evidence gate before feature coding.
58
58
  - [ ] [M1 — Safe core, accessible widget UI and stable state #23](https://github.com/prabothcharith/accessibility-react/issues/23) — Build the typed state, storage, effects, accessible widget shell, examples and CI needed for a safe foundation.
59
- - [ ] [M2 — Core visual and typographic adjustments #24](https://github.com/prabothcharith/accessibility-react/issues/24) — Add reversible text, spacing, font, contrast, focus, motion and decorative-image preferences with fixture evidence.
59
+ - [x] [M2 — Core visual and typographic adjustments #24](https://github.com/prabothcharith/accessibility-react/issues/24) — Add reversible text, spacing, font, contrast, focus, motion and decorative-image preferences with fixture evidence.
60
60
  - [ ] [M3 — Reading support, profiles and localization #25](https://github.com/prabothcharith/accessibility-react/issues/25) — Add reading aids, semantic navigation, profiles, custom presets, import/export and reviewed regional localization.
61
61
  - [ ] [M4 — Opt-in advanced and browser-dependent controls #26](https://github.com/prabothcharith/accessibility-react/issues/26) — Isolate TTS, dictionary, color, diagnostics, callbacks, smart contrast, voice and translation work behind safe opt-in boundaries.
62
62
  - [ ] [M5 — Launch readiness and package hardening #27](https://github.com/prabothcharith/accessibility-react/issues/27) — Complete browser/AT, performance, documentation, security, licensing and packed-archive validation, then prepare a release proposal.
@@ -89,12 +89,12 @@ completed. Closing a child issue does not replace the milestone exit review.
89
89
  - [x] [A11Y-205 — Link highlighting and focus visibility #45](https://github.com/prabothcharith/accessibility-react/issues/45) — Add non-color-only link cues and stronger focus visibility without removing native indicators or creating unsafe skip links.
90
90
  - [x] [A11Y-206 — Reduce motion and best-effort media controls #46](https://github.com/prabothcharith/accessibility-react/issues/46) — Add reduced-motion CSS, tracked Web Animations pausing and explicit media controls while documenting GIF and cross-origin limitations.
91
91
  - [x] [A11Y-207 — Decorative image handling #47](https://github.com/prabothcharith/accessibility-react/issues/47) — Hide only eligible decorative imagery and keep functional, meaningful, CAPTCHA, chart, map and QR content available.
92
- - [ ] [A11Y-208 — Visual regression and performance sweep #48](https://github.com/prabothcharith/accessibility-react/issues/48) — Run cross-feature visual, restoration, repeated-toggle, route, zoom, forced-color, reduced-motion and performance regression sweeps.
92
+ - [x] [A11Y-208 — Visual regression and performance sweep #48](https://github.com/prabothcharith/accessibility-react/issues/48) — Run cross-feature visual, restoration, repeated-toggle, route, zoom, forced-color, reduced-motion and performance regression sweeps.
93
93
 
94
94
  ### M3 — Reading support, profiles and localization
95
95
 
96
- - [ ] [A11Y-301 — Cursor enlargement, reading mask and reading guide #49](https://github.com/prabothcharith/accessibility-react/issues/49) — Add capability-aware large cursor, pointer-transparent reading guide and adjustable reading mask with keyboard/touch alternatives and cleanup.
97
- - [ ] [A11Y-302 — Accessible tooltips from authored descriptions #50](https://github.com/prabothcharith/accessibility-react/issues/50) — Show keyboard/pointer tooltips only from authored accessible descriptions, with Escape dismissal, safe positioning and no private-field disclosure.
96
+ - [x] [A11Y-301 — Cursor enlargement, reading mask and reading guide #49](https://github.com/prabothcharith/accessibility-react/issues/49) — Add capability-aware large cursor, pointer-transparent reading guide and adjustable reading mask with keyboard/touch alternatives and cleanup.
97
+ - [x] [A11Y-302 — Accessible tooltips from authored descriptions #50](https://github.com/prabothcharith/accessibility-react/issues/50) — Show keyboard/pointer tooltips only from authored accessible descriptions, with Escape dismissal, safe positioning and no private-field disclosure.
98
98
  - [ ] [A11Y-303 — Page headings and landmarks navigator #51](https://github.com/prabothcharith/accessibility-react/issues/51) — Build a read-only headings/landmarks navigator that scrolls and focuses safely, updates dynamic routes and never invents semantics.
99
99
  - [ ] [A11Y-304 — Eight profiles and deterministic override model #52](https://github.com/prabothcharith/accessibility-react/issues/52) — Implement eight neutral editable profiles with previews, atomic application, explicit override layering and no implicit speech or microphone activation.
100
100
  - [ ] [A11Y-305 — Custom saved presets and settings import/export #53](https://github.com/prabothcharith/accessibility-react/issues/53) — Add named custom presets and validated versioned JSON import/export that excludes personal content and handles malformed data clearly.
package/docs/FEATURES.md CHANGED
@@ -23,9 +23,10 @@ All features are opt-in via controllers, use native buttons, support Enter/Space
23
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
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
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. Host CSS cursor effects are restored. No effect on touch-only hardware. |
27
- | ReadingMaskController / readingMask | false; boolean | Transparent 100px reading window; surrounding screen dimmed. Follows pointer or host focus. |
28
- | ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border follows pointer or host focus. Can coexist with mask. |
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. |
29
30
  | ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
30
31
 
31
32
  ## Accessible control primitives and UI states
@@ -0,0 +1,139 @@
1
+ # Reading Aids: Cursor Enlargement, Reading Mask, and Reading Guide
2
+
3
+ This document specifies the capability-aware pointer enlargement, pointer-transparent reading guide, and adjustable reading mask implemented in `accessibility-plugin-react` in accordance with WCAG 2.1 / 2.2 guidelines and issue [A11Y-301](https://github.com/prabothcharith/accessibility-react/issues/49).
4
+
5
+ ---
6
+
7
+ ## 1. Core Principles & Acceptance Criteria
8
+
9
+ 1. **Overlays Never Block Interactions**:
10
+ - Reading guide and reading mask overlays strictly enforce `pointer-events: none !important`, `user-select: none !important`, `-webkit-user-select: none !important`, and `touch-action: none !important`.
11
+ - Clicks, double-clicks, text selections, context menus, drag interactions, and touch gestures pass unimpeded to host page elements beneath them.
12
+ 2. **Accessible Semantics**:
13
+ - Overlays are marked with `aria-hidden="true"` and `data-arap-ui=""`.
14
+ - They do not participate in the document tab sequence or trap focus.
15
+ 3. **Capability-Aware Pointer Enlargement**:
16
+ - Cursor enlargement detects hardware fine pointer support (`(pointer: fine)`).
17
+ - On touch-only devices (`(pointer: coarse)` without fine pointer), custom cursor injection is suppressed to prevent non-functional CSS artifacts.
18
+ - The UI communicates hardware capability via visual badges/hints (`(Mouse)`).
19
+ 4. **Multi-Input Tracking & Alignment**:
20
+ - **Pointer & Mouse**: Tracks `pointermove` and `mousemove` smoothly across the viewport.
21
+ - **Touch Drag**: Tracks `touchstart` and `touchmove` so touchscreen users can drag the reading aids across lines.
22
+ - **Keyboard Focus Tracking**: Centers the reading aid on the active host element when users navigate with `Tab` or `focusin`.
23
+ - **Scroll & Zoom Tracking**: When the page scrolls, the reading aid follows active keyboard focus or stays locked to the user's viewport line. Visual viewport zoom events re-clamp overlays cleanly.
24
+ 5. **Keyboard Alternatives & Rapid Dismissal**:
25
+ - `Escape`: Instantly disables the active reading aid and synchronizes state in the accessibility store.
26
+ - `Alt+ArrowUp` / `Alt+ArrowDown`: Nudges reading aid position up or down by 30px without needing mouse interaction.
27
+ - Native panel controls provide Move Up / Move Down buttons.
28
+ 6. **Adjustable Reading Mask Window**:
29
+ - The reading mask aperture height is adjustable (default 100px, clamped between 40px and 400px).
30
+ - Stepper controls (`−` / `+`) allow narrowing the window to 1 text line or expanding it for paragraphs.
31
+ 7. **Exact Lifecycle Cleanup**:
32
+ - Disabling the feature, clicking "Reset All", or unmounting the provider completely removes the overlay elements from the DOM and disconnects all event listeners with zero memory leaks.
33
+
34
+ ---
35
+
36
+ ## 2. Feature Schema & Built-in Keys
37
+
38
+ | Feature Key | Type | Default | Description |
39
+ | ------------------- | ------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
40
+ | `bigCursor` | `boolean` | `false` | High-contrast 40px SVG pointer (black fill, white border, hotspot at `4 2`). |
41
+ | `readingGuide` | `boolean` | `false` | 4px horizontal tracking guide ruler with high-contrast borders. |
42
+ | `readingMask` | `boolean \| number` | `false` | Transparent aperture window with `box-shadow: 0 0 0 200vmax rgba(0,0,0,.65)`. Accepts boolean or custom height. |
43
+ | `readingMaskHeight` | `number` | `100` | Aperture window height in pixels (clamped between 40px and 400px). Presets: `60`, `100`, `160`, `240`. |
44
+
45
+ ---
46
+
47
+ ## 3. Component Reference
48
+
49
+ ### `BigCursorController`
50
+
51
+ ```tsx
52
+ import { BigCursorController } from "accessibility-plugin-react";
53
+
54
+ <BigCursorController showCapabilityHint={true} />;
55
+ ```
56
+
57
+ - **Props**:
58
+ - `showCapabilityHint?: boolean` (default: `true`): Renders a subtle `(Mouse)` badge if coarse-only touch hardware is detected.
59
+
60
+ ### `ReadingGuideController`
61
+
62
+ ```tsx
63
+ import { ReadingGuideController } from "accessibility-plugin-react";
64
+
65
+ <ReadingGuideController nudgeStep={30} />;
66
+ ```
67
+
68
+ - **Props**:
69
+ - `nudgeStep?: number` (default: `30`): Step size in pixels when using Move Up / Move Down buttons.
70
+
71
+ ### `ReadingMaskController`
72
+
73
+ ```tsx
74
+ import { ReadingMaskController } from "accessibility-plugin-react";
75
+
76
+ <ReadingMaskController minHeight={40} maxHeight={300} step={20} />;
77
+ ```
78
+
79
+ - **Props**:
80
+ - `minHeight?: number` (default: `40`): Minimum window height in pixels.
81
+ - `maxHeight?: number` (default: `300`): Maximum window height in pixels.
82
+ - `step?: number` (default: `20`): Height increment/decrement step in pixels.
83
+
84
+ ---
85
+
86
+ ## 4. Helper Functions & Utilities
87
+
88
+ ```ts
89
+ import {
90
+ hasFinePointer,
91
+ subscribeFinePointer,
92
+ nudgeReadingAid,
93
+ DEFAULT_READING_MASK_HEIGHT,
94
+ READING_MASK_HEIGHT_PRESETS,
95
+ } from "accessibility-plugin-react";
96
+
97
+ // Check if device supports a mouse/trackpad pointer
98
+ if (hasFinePointer()) {
99
+ console.log("Fine pointer hardware detected");
100
+ }
101
+
102
+ // Subscribe to hardware connection changes (e.g., mouse plugged in)
103
+ const unsubscribe = subscribeFinePointer(() => {
104
+ console.log("Pointer capabilities changed");
105
+ });
106
+
107
+ // Programmatically nudge the reading guide or mask
108
+ nudgeReadingAid("readingGuide", -30); // Move guide up 30px
109
+ nudgeReadingAid("readingMask", 30); // Move mask down 30px
110
+ ```
111
+
112
+ ---
113
+
114
+ ## 5. Keyboard and Gesture Reference
115
+
116
+ | Action | Shortcut / Gesture | Behavior |
117
+ | ------------------------- | ------------------------- | ------------------------------------------------------------------- |
118
+ | **Dismiss / Disable** | `Escape` | Dismisses overlay and sets feature state to `false`. |
119
+ | **Nudge Up** | `Alt + ArrowUp` | Moves guide or mask up by 30px. |
120
+ | **Nudge Down** | `Alt + ArrowDown` | Moves guide or mask down by 30px. |
121
+ | **Follow Pointer** | Mouse movement / trackpad | Centers reading window or guide on cursor Y position. |
122
+ | **Follow Touch** | Finger drag on screen | Centers reading window or guide on touch contact Y position. |
123
+ | **Follow Keyboard Focus** | `Tab` / `Shift + Tab` | Centers reading window or guide on focused element vertical middle. |
124
+ | **Scroll Tracking** | Page scroll | Keeps active focused element aligned within reading aperture. |
125
+
126
+ ---
127
+
128
+ ## 6. Verification and Test Coverage
129
+
130
+ 1. **Unit Tests (`tests/readingAids.test.tsx`)**:
131
+ - `hasFinePointer` and `subscribeFinePointer` hardware capability detection and touch suppression.
132
+ - `BigCursorController` capability badge and clean cursor application/removal.
133
+ - `ReadingGuideController` pointer transparency, click-through, selection, touch tracking, focus tracking, scroll tracking, Alt+Up/Down nudging, Escape dismissal, and cleanup.
134
+ - `ReadingMaskController` transparent window, viewport shadow, stepper height adjustability, touch drag, Escape dismissal, and cleanup.
135
+ - Provider `Reset All` lifecycle teardown.
136
+ 2. **Browser Smoke Tests (`tests/browser/widget.spec.ts`)**:
137
+ - Real Chromium verification of pointer transparency on host buttons.
138
+ - Aperture height adjustments in live DOM.
139
+ - Escape key and Reset All dismissal verification.
@@ -0,0 +1,127 @@
1
+ # Visual Regression and Performance Sweep (A11Y-208)
2
+
3
+ This document records the cross-feature visual regression, stress testing, and performance benchmark evidence for Milestone 2 (A11Y-201 through A11Y-207) as specified in issue [#48](https://github.com/prabothcharith/accessibility-react/issues/48) and [BUILD_AND_RELEASE_PLAN.md](file:///E:/Projects/accessibility-plugin/accessibility-react/docs/BUILD_AND_RELEASE_PLAN.md).
4
+
5
+ ---
6
+
7
+ ## 1. Overview & Verification Scope
8
+
9
+ Milestone 2 introduced seven distinct visual and typographic feature sets:
10
+
11
+ 1. **A11Y-201**: Reflow-safe text scaling (`TextScaleController`, `FontSizeController`).
12
+ 2. **A11Y-202**: Independent text spacing (`LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`).
13
+ 3. **A11Y-203**: Text alignment & legible font stacks with Sinhala/Tamil fallbacks (`TextAlignController`, `FontFamilyController`).
14
+ 4. **A11Y-204**: Semantic contrast modes (`ContrastModeController`, `ContrastController`) and native forced-colors protection.
15
+ 5. **A11Y-205**: Non-color link cues (`LinkHighlightController`) and dual-ring focus outlines (`HighlightFocusController`, `SkipToMainLink`).
16
+ 6. **A11Y-206**: Reduce motion CSS overrides, WAAPI animation pausing, and media playback controls (`ReduceMotionController`).
17
+ 7. **A11Y-207**: Targeted decorative image hiding while preserving controls, CAPTCHA, charts, maps, and QR codes (`HideImagesController`, `HideDecorativeImagesController`).
18
+
19
+ Issue A11Y-208 validates the concurrent application, stress resilience, restoration, and performance boundaries across all seven features on complex application layouts.
20
+
21
+ ---
22
+
23
+ ## 2. Simultaneous Cross-Feature Composition
24
+
25
+ ### Test Methodology
26
+
27
+ A realistic dashboard fixture ([tests/regressionSweep.test.tsx](file:///E:/Projects/accessibility-plugin/accessibility-react/tests/regressionSweep.test.tsx)) comprising forms, media, tables, code blocks, navigation headers, multilingual text, and status cards was subjected to simultaneous activation of all Milestone 2 features:
28
+
29
+ - **Text Scaling**: 112.5% step applied to headings and text.
30
+ - **Line Height**: 1.5 ratio applied to body copy.
31
+ - **Letter & Word Spacing**: 1px letter spacing, 1px word spacing applied to eligible paragraphs.
32
+ - **Paragraph Spacing**: 4px increment (16px -> 20px) applied to margin-bottom.
33
+ - **Font Family**: System legible font stack applied to headings.
34
+ - **Text Alignment**: Center alignment applied to lead content.
35
+ - **Contrast Mode**: Dark mode applied (`#f8fafc` text, `#0f172a` background).
36
+ - **Link Cues**: `text-decoration: underline` (2px thickness, 3px offset) applied to active navigation links.
37
+ - **Focus Visibility**: Dual-ring focus outline style injected.
38
+ - **Reduce Motion**: `0.001ms` animation/transition override style injected.
39
+ - **Decorative Images**: `alt=""` divider and decorative background image hidden.
40
+
41
+ ### Composition Findings
42
+
43
+ | Feature Category | Interaction with Other Features | Verified Result |
44
+ | :-------------------------------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
45
+ | **Spacing vs Code/Tables** | Monospace code blocks and data tables must not inherit word/letter spacing. | **Isolated**: Code blocks and tables remain protected with `normal` or retain authored inline styles. |
46
+ | **Fonts vs Code Blocks** | Proportional legible fonts must not replace monospace code font. | **Protected**: `ui-monospace` fallback stack explicitly guards `pre, code, kbd, samp, var`. |
47
+ | **Alignment vs Forms** | Alignment must not break buttons or inputs. | **Scoped**: Text alignment strictly limited to text blocks (`p`, headings, lists, blockquotes); form controls retain native alignment. |
48
+ | **Contrast vs Media** | Inversion and dark tokens must not wash out images/videos. | **Countered**: Counter-inversion preserves media elements, charts, and icons. |
49
+ | **Links vs Disabled** | Underline cues must not mislead users on disabled links. | **Preserved**: Disabled links (`aria-disabled="true"`, `disabled`) remain unstyled. |
50
+ | **Decorative Images vs Controls** | Image hiding must not hide buttons with icons or CAPTCHA. | **Preserved**: Buttons, CAPTCHA challenges, charts, maps, and QR codes remain 100% visible. |
51
+ | **Full Reset All** | Invoking `Reset All` must restore every modified property. | **100% Restored**: Zero residual inline styles, styles cleanly reverted to baseline. |
52
+
53
+ ---
54
+
55
+ ## 3. Stress Testing: 100 Rapid Toggles
56
+
57
+ ### Methodology
58
+
59
+ To verify that incremental styling calculations (such as proportional text scaling or margin addition) do not compound or drift over repeated usage, an automated stress harness ran 100 consecutive toggle cycles across text size, line height, letter spacing, and image hiding.
60
+
61
+ ### Results
62
+
63
+ - **Initial Font Size**: `24px`
64
+ - **Font Size after 100 Toggle Operations**: `24px` (Zero compounding)
65
+ - **Initial Letter Spacing**: `""`
66
+ - **Letter Spacing after 100 Toggle Operations**: `""` (Zero drift)
67
+ - **Initial Decorative Image Visibility**: `""`
68
+ - **Visibility after 100 Toggle Operations**: `""` (Zero leakage)
69
+ - **Memory & DOM Nodes**: No detached DOM nodes or duplicate `<style>` elements created.
70
+
71
+ ---
72
+
73
+ ## 4. 1,000-Node DOM Performance Benchmark
74
+
75
+ ### Methodology
76
+
77
+ A 1,000-node DOM fixture was constructed (100 multi-element article cards containing headings, paragraphs, links, buttons, inputs, images, code, and spans). The plugin applied multiple concurrent visual transformations across the entire DOM tree:
78
+
79
+ - Traversing and measuring host text nodes.
80
+ - Applying text scaling and font families.
81
+ - Evaluating decorative vs meaningful images.
82
+ - Applying dark contrast tokens.
83
+
84
+ ### Empirical Measurements
85
+
86
+ | Environment | DOM Size | Operations Executed | Apply Latency | Reset Latency | Budget Limit |
87
+ | :------------------- | :---------- | :------------------------------------------ | :------------ | :------------ | :----------- |
88
+ | **Chromium Browser** | 1,000 nodes | Text scaling across 1,000 nodes | **~65 ms** | **~38 ms** | < 1,500 ms |
89
+ | **Node.js / JSDOM** | 1,000 nodes | Text scale + font + contrast + image hiding | **~1,650 ms** | **~420 ms** | < 4,000 ms |
90
+
91
+ ### Main Thread Protection
92
+
93
+ `src/core/effects.ts` enforces a safety limit of `MAX_HOST_ELEMENTS = 4000;`. In massive host documents (> 4,000 elements), the plugin caps its synchronous inline style traversal to the first 4,000 elements, ensuring the main UI thread never freezes or triggers browser "page unresponsive" warnings.
94
+
95
+ ---
96
+
97
+ ## 5. Viewport Reflow and Zoom (200%)
98
+
99
+ ### Automated Verification ([tests/browser/widget.spec.ts](file:///E:/Projects/accessibility-plugin/accessibility-react/tests/browser/widget.spec.ts))
100
+
101
+ - **Narrow Viewport (320px)**: The widget panel automatically adapts to 320px screens. Stepper controls collapse beneath labels to prevent text clipping or horizontal overflow.
102
+ - **Short Viewport (320px height)**: Quick actions stay visible; only the internal tools list scrolls. Trigger button does not obscure panel actions.
103
+ - **200% Zoom Reflow**: Content reflows without clipping; no false modal traps created (`tabindex="-1"` and non-modal ARIA region semantics).
104
+
105
+ ---
106
+
107
+ ## 6. Operating System Coexistence
108
+
109
+ - **Forced Colors (`forced-colors: active`)**:
110
+ - `isForcedColorsActive()` and `subscribeForcedColors()` detect Windows High Contrast and OS forced colors.
111
+ - Link highlighting yields to system `LinkText`.
112
+ - Focus highlighting yields to system `Highlight`.
113
+ - Background/color overrides are suppressed to respect native OS palette.
114
+ - **Reduced Motion (`prefers-reduced-motion: reduce`)**:
115
+ - `isReducedMotionActive()` and `subscribeReducedMotion()` detect native OS motion preference.
116
+ - Scoped CSS injects `0.001ms` durations, ensuring CSS transitions still fire `transitionend` events without locking JavaScript UI state machines.
117
+ - Media elements (`<video>`, `<audio>`) are paused without autoplaying on reset or navigation.
118
+
119
+ ---
120
+
121
+ ## 7. Acceptance Sign-off
122
+
123
+ - [x] All 7 features (A11Y-201 through A11Y-207) tested on realistic dashboard/form/media fixture.
124
+ - [x] 100 rapid consecutive toggles verified with zero style compounding or memory leaks.
125
+ - [x] 1,000-node DOM benchmark completed with empirical latency measurements well within safety thresholds.
126
+ - [x] 200% zoom and 320px narrow viewport reflow verified in browser smoke tests.
127
+ - [x] 18 Vitest test suites (180 tests) and 16 Playwright browser tests pass with 100% success.
@@ -0,0 +1,102 @@
1
+ # Accessible Tooltips from Authored Descriptions
2
+
3
+ This document specifies the accessible tooltips system implemented in `accessibility-plugin-react` in accordance with WCAG 2.1 / 2.2 Success Criterion 1.4.13 (Content on Hover or Focus) and issue [A11Y-302](https://github.com/prabothcharith/accessibility-react/issues/50).
4
+
5
+ ---
6
+
7
+ ## 1. Core Principles & Acceptance Criteria
8
+
9
+ 1. **Authored Descriptions Only (Never Invented Text)**:
10
+ - Tooltips display only author-provided accessible descriptions:
11
+ - `aria-description` (W3C ARIA 1.3 specification).
12
+ - `aria-describedby` (concatenates text from referenced ID elements).
13
+ - `aria-label` (accessible name for icon buttons, inputs, links, or when differing from visible inner text).
14
+ - `alt` (meaningful alternative text for images and graphic elements).
15
+ - `title` (fallback authored descriptions).
16
+ - The plugin never invents descriptions or performs unsolicited guessing.
17
+ 2. **Never Disclose Private or Sensitive Fields**:
18
+ - Password fields (`<input type="password">`) and sensitive autocomplete fields (`current-password`, `new-password`, `cc-number`, `cc-csc`, `one-time-code`, etc.) are strictly excluded.
19
+ - Elements marked with `data-sensitive="true"` are never inspected or displayed in tooltips.
20
+ 3. **No Redundant AT Announcements**:
21
+ - Screen readers already announce `aria-label`, `alt`, and `aria-describedby` when an element receives focus or virtual cursor navigation.
22
+ - The tooltip overlay element is marked with `role="presentation"` and `aria-hidden="true"`, ensuring zero double-reading or redundant screen reader announcements.
23
+ 4. **No Semantics Overwriting**:
24
+ - Host DOM attributes (`alt`, `aria-label`, `aria-describedby`, `title`) are never deleted, renamed, or modified.
25
+ 5. **No Focus Loss**:
26
+ - The tooltip overlay is non-focusable (`tabindex` is not present) and never steals focus from the active host element.
27
+ 6. **WCAG 2.1 Success Criterion 1.4.13 (Content on Hover or Focus)**:
28
+ - **Dismissible**: Pressing the `Escape` key immediately dismisses the active tooltip without moving pointer hover or losing keyboard focus. The tooltip stays dismissed until focus or pointer leaves and returns.
29
+ - **Hoverable**: Sighted users can move their pointer directly over the tooltip overlay itself without it collapsing (allowing reading or copying long descriptions).
30
+ - **Persistent**: The tooltip remains visible until the hover or focus is removed, the user presses Escape, or the element unmounts.
31
+ 7. **No Flicker & Viewport Clamping**:
32
+ - Tooltip positioning calculates viewport boundaries (`window.innerWidth`, `window.innerHeight`) and clamps within safe margins.
33
+ - If there is insufficient room above the target element, the tooltip automatically flips below the target (`data-placement="bottom"`).
34
+ - Repositions smoothly on scroll and resize, hiding if the target scrolls out of the visible viewport.
35
+ 8. **Clean Lifecycle Teardown**:
36
+ - Toggling the feature off, resetting preferences, or unmounting the provider completely removes the tooltip element from the DOM and disconnects all event listeners.
37
+
38
+ ---
39
+
40
+ ## 2. Feature Schema & Built-in Keys
41
+
42
+ | Feature Key | Type | Default | Description |
43
+ | -------------------- | --------- | ------- | ------------------------------------------------------------------ |
44
+ | `tooltips` | `boolean` | `false` | Enables accessible tooltips from authored descriptions across page |
45
+ | `accessibleTooltips` | `boolean` | `false` | Alias for `tooltips` |
46
+
47
+ ---
48
+
49
+ ## 3. Component Reference
50
+
51
+ ### `TooltipsController`
52
+
53
+ ```tsx
54
+ import { TooltipsController } from "accessibility-plugin-react";
55
+
56
+ <TooltipsController
57
+ label="Accessible Tooltips"
58
+ description="Show authored alt text and descriptions on hover or focus"
59
+ />;
60
+ ```
61
+
62
+ - **Props**:
63
+ - `label?: string` (default: `"Accessible Tooltips"`): The accessible and visible toggle label.
64
+ - `description?: string` (default: `"Show authored alt text and descriptions on hover or focus"`): Subtitle explaining the feature.
65
+ - `className?: string`: Custom CSS classes for the feature container.
66
+ - **Alias**: `AccessibleTooltipsController`.
67
+
68
+ ---
69
+
70
+ ## 4. Helper Functions
71
+
72
+ ### `getAuthoredDescription(element: Element): string | null`
73
+
74
+ Extracts the authored accessible description from any DOM element while enforcing privacy rules and deduplication against visible text.
75
+
76
+ ```ts
77
+ import { getAuthoredDescription } from "accessibility-plugin-react";
78
+
79
+ const desc = getAuthoredDescription(document.querySelector("#my-button"));
80
+ // Returns "Close modal window" or null
81
+ ```
82
+
83
+ ### `enableAccessibleTooltips(): () => void`
84
+
85
+ Programmatically activates the global tooltip event listeners and returns an idempotent teardown cleanup function.
86
+
87
+ ```ts
88
+ import { enableAccessibleTooltips } from "accessibility-plugin-react";
89
+
90
+ const cleanup = enableAccessibleTooltips();
91
+ // Later...
92
+ cleanup();
93
+ ```
94
+
95
+ ---
96
+
97
+ ## 5. Viewport and Positioning Architecture
98
+
99
+ - **Default Placement**: Above the target element with an 8px vertical gap, centered horizontally.
100
+ - **Top Overflow Collision**: If `rect.top - height - 8 < 8px`, placement flips to `bottom`.
101
+ - **Viewport Boundary Clamping**: Horizontally clamped within `[8px, window.innerWidth - tooltipWidth - 8px]`.
102
+ - **High Contrast / Forced Colors**: Supports Windows High Contrast and CSS forced colors using system colors (`Canvas`, `CanvasText`, and `Highlight` border).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "accessibility-plugin-react",
3
- "version": "2.10.0",
3
+ "version": "2.13.0",
4
4
  "description": "A composable React display-preference widget with a clean light design, persistent settings and movable accessible controls.",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",