accessibility-plugin-react 2.5.0 → 2.7.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
@@ -1023,3 +1023,19 @@
1023
1023
  color: var(--arap-text);
1024
1024
  border-color: var(--arap-text);
1025
1025
  }
1026
+ .arap-notice {
1027
+ grid-column: 1 / -1;
1028
+ margin-top: 6px;
1029
+ padding: 8px 12px;
1030
+ border-radius: 8px;
1031
+ font-size: 12px;
1032
+ line-height: 1.45;
1033
+ background: #fefce8;
1034
+ border: 1px solid #fef08a;
1035
+ color: #854d0e;
1036
+ }
1037
+ .arap-notice-warning {
1038
+ background: #fffbeb;
1039
+ border-color: #fde68a;
1040
+ color: #92400e;
1041
+ }
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`, `LineHeightControllerProps`, `LetterSpacingControllerProps`, `WordSpacingControllerProps`, `ParagraphSpacingControllerProps`, `ScriptSpacingConstraints`, `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`, `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`.
53
+ Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`, `FontFamilyController`, `TextAlignController`, `ContrastController`, `ContrastModeController`.
54
54
 
55
- Exported typography and reflow utilities: `TEXT_SCALE_STEPS`, `TEXT_SCALE_PROTECTED_SELECTOR`, `isProtectedFromTextScale`, `LINE_HEIGHT_STEPS`, `LINE_HEIGHT_RATIOS`, `TEXT_SPACING_EXCLUDED_SELECTOR`, `isProtectedFromTextSpacing`, `getScriptSpacingConstraints`.
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`.
56
56
 
57
57
  Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
58
58
 
@@ -84,8 +84,8 @@ completed. Closing a child issue does not replace the milestone exit review.
84
84
 
85
85
  - [x] [A11Y-201 — Bigger text and reflow-safe scaling #41](https://github.com/prabothcharith/accessibility-react/issues/41) — Add stepwise 1x–2x text scaling through reflow-safe scoped styles without nested compounding, clipping or changes to protected controls.
86
86
  - [x] [A11Y-202 — Letter, word, paragraph spacing and line height #42](https://github.com/prabothcharith/accessibility-react/issues/42) — Add independent letter, word and paragraph spacing plus line-height options with script-aware limits and restoration tests.
87
- - [ ] [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
- - [ ] [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.
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
+ - [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
  - [ ] [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
  - [ ] [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
  - [ ] [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.
@@ -0,0 +1,73 @@
1
+ # Contrast Modes, Semantic Tokens and Native Forced-Colors Protection
2
+
3
+ This document details the contrast architecture, semantic tokens, element and state protections, and native operating system forced-colors integration in `accessibility-plugin-react`.
4
+
5
+ ---
6
+
7
+ ## 1. Contrast Modes and Semantic Tokens
8
+
9
+ The library provides five semantic contrast modes, configurable via `ContrastModeController` or `ContrastController`:
10
+
11
+ | Mode | Key | Description | Semantic Palette |
12
+ | :----------------- | :----------------------- | :---------------------------------------------- | :------------------------------------------------------------------------- |
13
+ | **Original / Off** | `off` / `original` / `0` | Restores original host styles without injection | N/A |
14
+ | **Light** | `light` | Crisp, high-clarity light theme | Background: `#ffffff`, Text: `#0f172a`, Border: `#94a3b8`, Link: `#0284c7` |
15
+ | **Dark** | `dark` | Deep dark mode with legible ink tones | Background: `#0f172a`, Text: `#f8fafc`, Border: `#475569`, Link: `#38bdf8` |
16
+ | **High Contrast** | `high` | Strict WCAG AAA (>= 7:1) high contrast | Background: `#000000`, Text: `#ffffff`, Border: `#ffffff`, Link: `#93c5fd` |
17
+ | **Invert** | `invert` | Luminance inversion with media preservation | Outer: `invert(1)`, Media: counter-inverted `invert(1)` |
18
+
19
+ In addition to semantic tokens, historical custom palettes (`yellow-on-black`, `white-on-black`, `blue-on-yellow`, `black-on-white`) and continuous filter multipliers (`reduced` 0.5×, `low` 1.25×, `high` 1.5×, `extra` 2.0×) are preserved for full backward compatibility.
20
+
21
+ ---
22
+
23
+ ## 2. Element & State Protections
24
+
25
+ Indiscriminate CSS filters or universal background overrides destroy non-text elements, chart visualizations, and critical interactive state cues. `isProtectedFromContrast(element)` strictly protects the following:
26
+
27
+ 1. **Images & Media**:
28
+ - `img`, `picture`, `picture *`, `video`, `canvas`
29
+ - Opaque background colors are never forced onto images or videos.
30
+ 2. **Graphics, SVGs & Charts**:
31
+ - `svg`, `svg *`, `[role="img"]`, `[role="graphics-document"]`, `[role="graphics-symbol"]`
32
+ - Data visualizations, vector diagrams, and charts remain clear and undistorted.
33
+ 3. **Icon Fonts & Glyph Elements**:
34
+ - `[data-icon]`, `i[class*="icon"]`, `span[class*="icon"]`, `i[class*="fa-"]`, `i[class*="material-symbols"]`, `i[class*="lucide"]`
35
+ 4. **Form Validation Error States**:
36
+ - `[aria-invalid="true"]`, `:invalid`, `.is-invalid`, `.invalid-feedback`, `[role="alert"]`
37
+ - Critical validation indicator colors (such as error red outlines, borders, and error copy) are never stripped or replaced with plain black/white text.
38
+ 5. **Disabled Control States**:
39
+ - `:disabled`, `[aria-disabled="true"]`, `[disabled]`
40
+ - Form buttons and inputs retain their disabled opacity and cues, preventing confusion between active and disabled controls.
41
+ 6. **Widget Isolation**:
42
+ - `.arap-root` and `[data-arap-ui]` remain completely isolated from page contrast overrides.
43
+
44
+ ---
45
+
46
+ ## 3. Media Preservation in Invert Mode
47
+
48
+ When page-level inversion (`invert(1)`) is enabled, photographs, artwork, and video streams normally become unsightly "negatives".
49
+
50
+ To protect user experience and visual accessibility:
51
+
52
+ - The library automatically queries all `img, video, canvas, picture, [role="img"]` within the inverted scope.
53
+ - It applies a counter-inversion (`filter: invert(1)`), which mathematical inversion cancels out (`invert(invert(X)) = X`).
54
+ - Photos, streaming video, and charts display with their true, natural photographic colors.
55
+ - When invert mode is disabled or reset, the counter-inversion filter is cleanly removed.
56
+
57
+ ---
58
+
59
+ ## 4. Operating System Forced-Colors Protection
60
+
61
+ Windows High Contrast Mode and operating systems supporting CSS `@media (forced-colors: active)` enforce system-level high-contrast palettes using keywords such as `Canvas`, `CanvasText`, `Highlight`, and `ButtonText`.
62
+
63
+ If an application forcibly applies inline colors or `contrast()` / `invert()` CSS filters while `forced-colors: active` is enabled, it interferes with user-configured system themes.
64
+
65
+ The library implements native forced-colors protection:
66
+
67
+ 1. **Detection**: `isForcedColorsActive()` inspects `window.matchMedia("(forced-colors: active)").matches`.
68
+ 2. **Non-Interference**: If forced-colors is active:
69
+ - `composeFilter()` yields `""`, suppressing CSS filter injections.
70
+ - Page inline background and color overrides are bypassed.
71
+ - Operating system high-contrast theme keywords remain in full control.
72
+ 3. **User Transparency**: `ContrastController` and `ContrastModeController` render an accessible notice:
73
+ > _Operating system high contrast (forced colors) is active._
package/docs/FEATURES.md CHANGED
@@ -2,26 +2,27 @@
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, reduced, yellow-on-black, white-on-black, blue-on-yellow | Off, 1.25×, 1.5×, 2×; reduced=0.5×. Named palettes set foreground/background instead of contrast filter. Palette doesn't guarantee contrast of all rendered content. |
14
- | SaturationController / saturation | 0; 0/1/2 | Off, 0.2×, 2× saturation. Composes with other filters. |
15
- | InvertColorsController / invertColors | false; boolean | Adds invert(1), includes content images. |
16
- | GrayscaleController / grayscale | false; boolean | Adds grayscale(1); saturation cannot restore color while this is active. |
17
- | LinkHighlightController / linkHighlight | false; false/true/yellow-on-black/blue-on-yellow/black-on-white | True uses dark text on pale yellow; palette buttons restore the original variants. Underlines a[href]. Toggle turns selected palette off. |
18
- | TextAlignController / textAlign | default; default/left/center/right/justify | Default restores host; left really forces left, including in RTL content. Justification can reduce readability for some users. |
19
- | 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. |
20
- | HideVideosController / hideVideos | false; boolean | Hides video and recognized YouTube/Vimeo embed URL patterns. Does not hide unrelated iframe documents, pause video or mute audio. |
21
- | 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. |
22
- | ReadingMaskController / readingMask | false; boolean | Transparent 100px reading window; surrounding screen dimmed. Follows pointer or host focus. |
23
- | ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border follows pointer or host focus. Can coexist with mask. |
24
- | 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
+ | 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. |
19
+ | 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. |
20
+ | 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. |
21
+ | HideVideosController / hideVideos | false; boolean | Hides video and recognized YouTube/Vimeo embed URL patterns. Does not hide unrelated iframe documents, pause video or mute audio. |
22
+ | 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. |
23
+ | ReadingMaskController / readingMask | false; boolean | Transparent 100px reading window; surrounding screen dimmed. Follows pointer or host focus. |
24
+ | ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border follows pointer or host focus. Can coexist with mask. |
25
+ | ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
25
26
 
26
27
  ## Accessible control primitives and UI states
27
28
 
package/docs/FONTS.md ADDED
@@ -0,0 +1,97 @@
1
+ # Font Stacks, Script Fallbacks and Text Alignment
2
+
3
+ This document outlines the font preferences, script fallbacks, monospace/glyph protection, and text alignment architecture implemented in `accessibility-plugin-react`.
4
+
5
+ ---
6
+
7
+ ## 1. Font Family Options
8
+
9
+ The plugin provides three primary font modes:
10
+
11
+ 1. **Default (`default` / `original`)**: Preserves the host application's original font typography without injecting overriding styles.
12
+ 2. **Legible (`legible`)**: Applies a modern, highly legible system font stack optimized for clean rendering across all operating systems, with explicit script fallbacks.
13
+ 3. **Dyslexia (`dyslexia-option` / `dyslexia`)**: Applies a dyslexia-friendly typeface stack prioritizing OpenDyslexic, weighted baselines, and soft rounded letterforms.
14
+
15
+ ---
16
+
17
+ ## 2. Font Stacks & Script Fallbacks
18
+
19
+ ### Legible Font Stack
20
+
21
+ ```css
22
+ font-family:
23
+ system-ui,
24
+ -apple-system,
25
+ BlinkMacSystemFont,
26
+ "Segoe UI",
27
+ Roboto,
28
+ "Helvetica Neue",
29
+ Arial,
30
+ "Noto Sans Sinhala",
31
+ "Iskoola Pota",
32
+ "Noto Sans Tamil",
33
+ "Latha",
34
+ "Nirmala UI",
35
+ sans-serif !important;
36
+ ```
37
+
38
+ - **Primary**: High-clarity system interfaces across macOS, iOS, Windows, Android, and Linux.
39
+ - **Sinhala Fallbacks**: `"Noto Sans Sinhala"`, `"Iskoola Pota"`, `"Nirmala UI"` ensure complex consonant clusters and vowel modifiers render cleanly without glyph truncation.
40
+ - **Tamil Fallbacks**: `"Noto Sans Tamil"`, `"Latha"`, `"Nirmala UI"` ensure clear loop clarity and distinct character legibility.
41
+
42
+ ### Dyslexia Font Stack
43
+
44
+ ```css
45
+ font-family:
46
+ OpenDyslexic, "Comic Sans MS", "Trebuchet MS", "Arial Rounded MT Bold",
47
+ "Noto Sans Sinhala", "Iskoola Pota", "Noto Sans Tamil", "Latha", sans-serif !important;
48
+ ```
49
+
50
+ - **Primary**: `OpenDyslexic` features heavy weighted bottoms, unique letter shaping, and wide apertures that counter letter rotation and flipping common in dyslexia.
51
+ - **Secondary Fallbacks**: `"Comic Sans MS"`, `"Trebuchet MS"`, and `"Arial Rounded MT Bold"` provide widely available fallback fonts with distinct non-symmetric letterforms (such as distinct `b` / `d` / `p` / `q`).
52
+ - **Script Fallbacks**: Preserves Sinhala and Tamil native readability.
53
+
54
+ ---
55
+
56
+ ## 3. Element & Symbol Protection
57
+
58
+ Font family overrides can break code blocks, symbol ligatures, and icon fonts if applied globally. The library strictly protects the following elements:
59
+
60
+ 1. **Code & Monospace Blocks**:
61
+ - `pre`, `code`, `kbd`, `samp`, `var`
62
+ - Explicitly isolated with `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace` to prevent inheriting global sans-serif or dyslexia fonts.
63
+ 2. **Icon Fonts & SVGs**:
64
+ - `svg`, `[data-icon]`, `i[class*="icon"]`, `span[class*="icon"]`, `i[class*="fa-"]`, `i[class*="material-symbols"]`, `i[class*="lucide"]`
65
+ - Preserves private use area (PUA) glyphs and vector icons without font corruption.
66
+ 3. **Exemptions & Widget UI**:
67
+ - Elements marked with `[data-arap-ignore]` or `[data-arap-exempt]`.
68
+ - Plugin widget internals (`.arap-root`, `[data-arap-ui]`).
69
+
70
+ ---
71
+
72
+ ## 4. Scoped Text Alignment & Justification Advisory
73
+
74
+ ### Scoped Logical Text Blocks
75
+
76
+ Global alignment overrides distort button text, form inputs, table layouts, and navigation headers. `TextAlignController` scopes alignment strictly to logical text blocks:
77
+
78
+ - Headings: `h1, h2, h3, h4, h5, h6, [role="heading"]`
79
+ - Content blocks: `p, li, blockquote, dt, dd, figcaption, [role="paragraph"]`
80
+
81
+ Protected elements (`table, th, td, button, input, select, textarea, pre, code`) remain untouched.
82
+
83
+ ### Justification Advisory (WCAG SC 1.4.8)
84
+
85
+ WCAG Success Criterion 1.4.8 (Visual Presentation) warns against fully justified text (aligned to both left and right margins), as uneven word spacing creates "rivers of white" running down the page, significantly impairing reading fluency for individuals with dyslexia or cognitive conditions.
86
+
87
+ When a user selects **Justify**, `TextAlignController` renders an accessible, polite notice (`role="note"`):
88
+
89
+ > _Justified text creates uneven word spacing ("rivers of white") that can impair readability._
90
+
91
+ ---
92
+
93
+ ## 5. Font Licensing & Attribution
94
+
95
+ - **OpenDyslexic**: Created by Abbie Gonzalez. Licensed under the [SIL Open Font License (OFL) v1.1](https://scripts.sil.org/OFL) and [Creative Commons Attribution 3.0 Unported](https://creativecommons.org/licenses/by/3.0/).
96
+ - **Noto Sans Sinhala & Noto Sans Tamil**: Designed by Google. Licensed under the [SIL Open Font License (OFL) v1.1](https://scripts.sil.org/OFL).
97
+ - **System Fonts** (`system-ui`, `Segoe UI`, `SF Pro`, `Roboto`, `Iskoola Pota`, `Latha`, `Nirmala UI`): Pre-installed native operating system fonts utilized via standard CSS fallback stacks without redistribution.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "accessibility-plugin-react",
3
- "version": "2.5.0",
3
+ "version": "2.7.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",