accessibility-plugin-react 2.8.0 → 2.10.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/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`, `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`, `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`, `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`, `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`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`.
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`.
56
56
 
57
57
  Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
58
58
 
@@ -87,8 +87,8 @@ completed. Closing a child issue does not replace the milestone exit review.
87
87
  - [x] [A11Y-203 — Text alignment, legible fonts and language fallback #43](https://github.com/prabothcharith/accessibility-react/issues/43) — Add scoped text alignment and legally distributable readable font choices with Sinhala/Tamil fallbacks while protecting icons, code and symbols.
88
88
  - [x] [A11Y-204 — Contrast modes and native forced-color protection #44](https://github.com/prabothcharith/accessibility-react/issues/44) — Add targeted original/light/dark/high/invert contrast modes that preserve host content and respect forced colors and other native settings.
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
- - [ ] [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
- - [ ] [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.
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
+ - [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
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.
93
93
 
94
94
  ### M3 — Reading support, profiles and localization
@@ -0,0 +1,176 @@
1
+ # Decorative Image Handling
2
+
3
+ This document specifies how `accessibility-plugin-react` identifies, scopes, and manages decorative images and CSS background images in accordance with WCAG 2.1 / 2.2 Success Criterion 1.1.1 (Non-text Content) and issue [A11Y-207](https://github.com/prabothcharith/accessibility-react/issues/47).
4
+
5
+ ---
6
+
7
+ ## 1. Core Principles
8
+
9
+ 1. **Hide only eligible decorative imagery**:
10
+ Only images that are unambiguously decorative are hidden when image hiding is activated.
11
+ 2. **Never hide functional or interactive controls**:
12
+ Images inside `<a>`, `<button>`, `<input>`, or elements with interactive ARIA roles (`button`, `link`, `menuitem`, `tab`) must remain visible so users do not lose critical interface affordances or touch targets.
13
+ 3. **Never hide essential, informative, or security content**:
14
+ - **CAPTCHA**: Verification puzzles and audio/visual challenge widgets are strictly protected.
15
+ - **Charts & Graphs**: Analytical visual representations, figures, and diagrams (`role="graphics-document"`, `role="figure"`, `.chart`, `.graph`, `.diagram`) remain fully available.
16
+ - **Maps**: Geolocation tiles, satellite maps, and interactive maps (`[role="region"][aria-label*="map"]`, `.map`, tile servers) remain visible.
17
+ - **QR & Barcodes**: Payment, login, and verification codes (`.qr`, `.barcode`) remain visible.
18
+ - **Math & Formulas**: Formulas (`role="math"`, `math`, `.math`) remain intact.
19
+ - **Meaningful Alt & Labels**: Any image with non-empty `alt`, `aria-label`, `aria-labelledby`, or `title` is considered informative and preserved.
20
+ 4. **Never fabricate alt text**:
21
+ The plugin never mutates, synthesizes, or generates AI/heuristic `alt` text or accessible names. It strictly acts as a client-side display-preference modifier.
22
+ 5. **Scoped CSS Background Images**:
23
+ CSS background images are only stripped from non-functional, non-meaningful layout containers. Buttons, links, CAPTCHA, charts, and maps retain their background graphics.
24
+ 6. **Idempotent and Reversible Lifecycle**:
25
+ Every visual override is tracked inline with priority preservation and completely restored upon toggle-off, reset, or plugin unmount.
26
+
27
+ ---
28
+
29
+ ## 2. Classification Logic
30
+
31
+ ### A. Functional or Meaningful Images (`isFunctionalOrMeaningfulImage`)
32
+
33
+ An image or element is deemed functional/meaningful and **MUST NEVER BE HIDDEN** if it satisfies any of the following:
34
+
35
+ - **Inside an interactive control**:
36
+ ```ts
37
+ el.closest(
38
+ "a, button, [role='button'], [role='link'], [role='menuitem'], [role='tab'], input, select, textarea, summary",
39
+ );
40
+ ```
41
+ - **CAPTCHA verification**:
42
+ ```ts
43
+ el.closest(
44
+ "[id*='captcha' i], [class*='captcha' i], [aria-label*='captcha' i], [data-captcha]",
45
+ ) ||
46
+ el.matches(
47
+ "[src*='captcha' i], [alt*='captcha' i], [title*='captcha' i], [id*='captcha' i], [class*='captcha' i]",
48
+ );
49
+ ```
50
+ - **Charts, Graphs, Figures, and Diagrams**:
51
+ ```ts
52
+ el.closest(
53
+ "[role='graphics-document'], [role='graphics-symbol'], [role='figure'], figure, [class*='chart' i], [id*='chart' i], [class*='graph' i], [id*='graph' i], [class*='diagram' i], [id*='diagram' i]",
54
+ ) ||
55
+ el.matches(
56
+ "[role='graphics-document'], [role='graphics-symbol'], [aria-roledescription*='chart' i]",
57
+ );
58
+ ```
59
+ - **Maps**:
60
+ ```ts
61
+ el.closest(
62
+ "[role='region'][aria-label*='map' i], [class*='map' i], [id*='map' i], [data-map]",
63
+ ) ||
64
+ el.matches(
65
+ "[src*='maps' i], [src*='tiles' i], [src*='openstreetmap' i], [src*='mapbox' i]",
66
+ );
67
+ ```
68
+ - **QR Codes and Barcodes**:
69
+ ```ts
70
+ el.closest(
71
+ "[class*='qr' i], [id*='qr' i], [class*='barcode' i], [id*='barcode' i]",
72
+ ) ||
73
+ el.matches(
74
+ "[src*='qr' i], [alt*='qr' i], [src*='barcode' i], [alt*='barcode' i]",
75
+ );
76
+ ```
77
+ - **Math Content**:
78
+ ```ts
79
+ el.closest("[role='math'], math, [class*='math' i]");
80
+ ```
81
+ - **Meaningful Authorship Attributes**:
82
+ - `alt` is non-empty (`alt.trim().length > 0`)
83
+ - `aria-label` is non-empty
84
+ - `aria-labelledby` is non-empty
85
+ - `title` is non-empty
86
+ - `role` is an informative role (not `presentation`, `none`, or bare unlabeled `img`)
87
+
88
+ ---
89
+
90
+ ### B. Eligible Decorative Images (`isEligibleDecorativeImage`)
91
+
92
+ An image or `<picture>` element is eligible to be hidden only if `isFunctionalOrMeaningfulImage(el)` is `false` AND it exhibits explicit decorative markup:
93
+
94
+ 1. **Empty alt attribute**: `el.hasAttribute("alt") && el.getAttribute("alt")?.trim() === ""`
95
+ 2. **Presentational ARIA role**: `el.getAttribute("role") === "presentation"` or `"none"`
96
+ 3. **Hidden from AT**: `el.getAttribute("aria-hidden") === "true"`
97
+ 4. **Explicit decorative cue**: `data-decorative="true"`, `.decorative`, or `.deco`
98
+ 5. **`<picture>` containers**: Any `<picture>` containing an eligible decorative child `<img>` is hidden as a unit.
99
+
100
+ Images that lack an `alt` attribute entirely without any decorative marker are **NOT** assumed decorative; omitting `alt` is an authoring defect, not proof of decorative intent. Hiding such images could remove informative visuals.
101
+
102
+ ---
103
+
104
+ ## 3. Component Usage
105
+
106
+ ### Standard Export: `HideImagesController`
107
+
108
+ ```tsx
109
+ import {
110
+ AccessibilityPlugin,
111
+ AccessibilityButton,
112
+ AccessibilityList,
113
+ HideImagesController,
114
+ } from "accessibility-plugin-react";
115
+
116
+ export function Settings() {
117
+ return (
118
+ <AccessibilityPlugin>
119
+ <AccessibilityButton />
120
+ <AccessibilityList>
121
+ <HideImagesController label="Hide Images" />
122
+ </AccessibilityList>
123
+ </AccessibilityPlugin>
124
+ );
125
+ }
126
+ ```
127
+
128
+ ### Semantic Alias: `HideDecorativeImagesController`
129
+
130
+ ```tsx
131
+ import { HideDecorativeImagesController } from "accessibility-plugin-react";
132
+
133
+ // Drop-in alias with semantic naming
134
+ <HideDecorativeImagesController label="Hide Decorative Images" />;
135
+ ```
136
+
137
+ ---
138
+
139
+ ## 4. Helper Utilities
140
+
141
+ Consumers can inspect elements using the exported predicates:
142
+
143
+ ```ts
144
+ import {
145
+ isEligibleDecorativeImage,
146
+ isFunctionalOrMeaningfulImage,
147
+ } from "accessibility-plugin-react";
148
+
149
+ const img = document.querySelector("#banner-photo");
150
+ if (isEligibleDecorativeImage(img)) {
151
+ console.log("Safe to hide as decorative imagery");
152
+ }
153
+ if (isFunctionalOrMeaningfulImage(img)) {
154
+ console.log("Protected informative or functional image");
155
+ }
156
+ ```
157
+
158
+ ---
159
+
160
+ ## 5. Verification Matrix
161
+
162
+ | Target | Condition | Expected Behavior |
163
+ | :----------------------------------------- | :---------------------------- | :---------------------------------- |
164
+ | `img[alt=""]` | Independent decorative image | `visibility: hidden` |
165
+ | `img[role="presentation"]` | Presentational image | `visibility: hidden` |
166
+ | `img[aria-hidden="true"]` | Screen-reader hidden image | `visibility: hidden` |
167
+ | `img[data-decorative]` | Marked decorative | `visibility: hidden` |
168
+ | `a > img[alt=""]` | Linked control image | **Visible** (retained) |
169
+ | `button > img` | Button control image | **Visible** (retained) |
170
+ | `img.captcha` | Security verification | **Visible** (retained) |
171
+ | `img.chart` / `[role="graphics-document"]` | Analytical visualization | **Visible** (retained) |
172
+ | `img[src*="tile.openstreetmap.org"]` | Map tile | **Visible** (retained) |
173
+ | `img.qr` | QR code | **Visible** (retained) |
174
+ | `div[style*="background-image"]` | Decorative container | `background-image: none !important` |
175
+ | `button[style*="background-image"]` | Functional control background | **Visible** (retained) |
176
+ | Reset / Unmount | Preferences cleared | All original styles restored |
package/docs/FEATURES.md CHANGED
@@ -2,30 +2,31 @@
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 / hideImages | false; boolean | Hides img/picture with visibility:hidden and removes CSS background images from HTML elements. Layout retained. SVG/canvas/pseudo-element imagery not hidden. |
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
- | 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. |
26
- | ReadingMaskController / readingMask | false; boolean | Transparent 100px reading window; surrounding screen dimmed. Follows pointer or host focus. |
27
- | ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border follows pointer or host focus. Can coexist with mask. |
28
- | 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
+ | 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. 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. |
29
+ | ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
29
30
 
30
31
  ## Accessible control primitives and UI states
31
32
 
@@ -0,0 +1,64 @@
1
+ # Reduce Motion and Best-Effort Media Controls
2
+
3
+ This document details the architecture, animation pausing mechanics, media autoplay controls, and technical limitations implemented under **[A11Y-206]**.
4
+
5
+ ---
6
+
7
+ ## 1. Overview and Standards Alignment
8
+
9
+ Vestibular disorders, epilepsy, motion sickness, and attention deficit conditions can be severely triggered by unexpected motion, parallax scrolling, flashing effects, and unprompted video/audio playback.
10
+
11
+ - **WCAG SC 2.2.2 (Pause, Stop, Hide - Level A)**: Any moving, blinking, or scrolling information that starts automatically and lasts more than five seconds must have a mechanism to pause, stop, or hide it.
12
+ - **WCAG SC 2.3.3 (Animation from Interactions - Level AAA)**: Motion animation triggered by interaction can be disabled unless the animation is essential to the functionality or the information being conveyed.
13
+
14
+ ---
15
+
16
+ ## 2. Technical Implementation
17
+
18
+ ### A. Scoped CSS Overrides
19
+
20
+ When `reduceMotion` is active, an isolated style sheet (`#arap-reduce-motion-style`) is injected:
21
+
22
+ ```css
23
+ *:not([data-arap-ui]):not([data-arap-ui] *),
24
+ *:not([data-arap-ui]):not([data-arap-ui] *)::before,
25
+ *:not([data-arap-ui]):not([data-arap-ui] *)::after {
26
+ animation-duration: 0.001ms !important;
27
+ animation-iteration-count: 1 !important;
28
+ transition-duration: 0.001ms !important;
29
+ scroll-behavior: auto !important;
30
+ }
31
+ ```
32
+
33
+ - **0.001ms vs. 0s**: Setting durations to `0.001ms` ensures that standard JavaScript transition/animation lifecycle callbacks (`transitionend`, `animationend`) still dispatch, preventing JavaScript framework state machines from freezing.
34
+ - **Scroll Behavior**: `scroll-behavior: auto !important` instantly terminates animated smooth scrolling.
35
+ - **Widget Boundary Protection**: Elements within `[data-arap-ui]` are excluded so widget open/close and placement operations remain smooth and predictable.
36
+
37
+ ### B. Tracked Web Animations API (WAAPI)
38
+
39
+ - Active animations running via `document.getAnimations()` on host elements are identified and paused:
40
+ ```ts
41
+ if (anim.playState === "running") {
42
+ anim.pause();
43
+ trackedAnimations.add(anim);
44
+ }
45
+ ```
46
+ - **Selective Teardown**: Upon reset or disabling `reduceMotion`, only animations that were originally running and explicitly paused by this plugin are resumed. Animations independently paused by the host application remain paused.
47
+
48
+ ### C. Explicit Media Autoplay Pausing
49
+
50
+ - Host HTML5 `<video>` and `<audio>` elements are queried and paused (`media.pause()`).
51
+ - **Never Autoplay on Reset**: Crucially, when `reduceMotion` is disabled or reset, media playback is **never automatically resumed**. Triggering unexpected sound or video upon resetting accessibility preferences or navigating routes violates user intent.
52
+
53
+ ### D. Operating System Motion Preference
54
+
55
+ - `isReducedMotionActive()` detects whether the host OS has `prefers-reduced-motion: reduce` configured.
56
+ - `subscribeReducedMotion()` listens reactively to changes in the operating system preference.
57
+ - `ReduceMotionController` renders an accessible, polite notice when OS reduced motion is active.
58
+
59
+ ---
60
+
61
+ ## 3. Known Limitations
62
+
63
+ - **Animated GIFs & APNGs**: Standard CSS and DOM APIs cannot halt frame playback within bitmap-encoded animated images without canvas re-rendering or DOM rewriting. Authors should provide static alternatives or use CSS video/animation formats.
64
+ - **Cross-Origin iframes**: Media players embedded inside cross-origin iframes (e.g., standard YouTube, Vimeo, or Spotify embeds) cannot be paused directly via cross-document scripts due to the browser's Same-Origin Policy.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "accessibility-plugin-react",
3
- "version": "2.8.0",
3
+ "version": "2.10.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",