accessibility-plugin-react 2.7.0 → 2.8.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/README.md +3 -0
- package/dist/index.d.mts +27 -1
- package/dist/index.d.ts +27 -1
- package/dist/index.js +514 -354
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +409 -253
- package/dist/index.mjs.map +1 -1
- package/dist/style.css +54 -0
- package/docs/API.md +3 -3
- package/docs/BUILD_AND_RELEASE_PLAN.md +1 -1
- package/docs/FEATURES.md +3 -0
- package/docs/LINKS_AND_FOCUS.md +65 -0
- package/package.json +1 -1
package/dist/style.css
CHANGED
|
@@ -556,6 +556,60 @@
|
|
|
556
556
|
background: var(--arap-surface);
|
|
557
557
|
color: var(--arap-accent);
|
|
558
558
|
}
|
|
559
|
+
.arap-skip-to-main {
|
|
560
|
+
position: fixed;
|
|
561
|
+
top: 12px;
|
|
562
|
+
left: 16px;
|
|
563
|
+
z-index: 2147483647;
|
|
564
|
+
width: 1px;
|
|
565
|
+
height: 1px;
|
|
566
|
+
margin: -1px;
|
|
567
|
+
padding: 0;
|
|
568
|
+
overflow: hidden;
|
|
569
|
+
clip-path: inset(50%);
|
|
570
|
+
white-space: nowrap;
|
|
571
|
+
border: 0;
|
|
572
|
+
pointer-events: none;
|
|
573
|
+
font-family: inherit;
|
|
574
|
+
font-size: 0.9375rem;
|
|
575
|
+
font-weight: 600;
|
|
576
|
+
text-decoration: none;
|
|
577
|
+
color: var(--arap-accent, #008060);
|
|
578
|
+
background: var(--arap-surface, #ffffff);
|
|
579
|
+
border-radius: 8px;
|
|
580
|
+
box-shadow:
|
|
581
|
+
0 10px 15px -3px rgba(0, 0, 0, 0.1),
|
|
582
|
+
0 4px 6px -4px rgba(0, 0, 0, 0.1);
|
|
583
|
+
}
|
|
584
|
+
.arap-skip-to-main:focus,
|
|
585
|
+
.arap-skip-to-main:focus-visible {
|
|
586
|
+
width: auto;
|
|
587
|
+
height: auto;
|
|
588
|
+
min-height: 44px;
|
|
589
|
+
margin: 0;
|
|
590
|
+
padding: 10px 18px;
|
|
591
|
+
clip-path: none;
|
|
592
|
+
overflow: visible;
|
|
593
|
+
white-space: normal;
|
|
594
|
+
pointer-events: auto;
|
|
595
|
+
border: 2px solid var(--arap-accent, #008060);
|
|
596
|
+
outline: 3px solid var(--arap-accent, #008060);
|
|
597
|
+
outline-offset: 3px;
|
|
598
|
+
display: inline-flex;
|
|
599
|
+
align-items: center;
|
|
600
|
+
justify-content: center;
|
|
601
|
+
}
|
|
602
|
+
@media (forced-colors: active) {
|
|
603
|
+
.arap-skip-to-main {
|
|
604
|
+
background: Canvas;
|
|
605
|
+
color: CanvasText;
|
|
606
|
+
border-color: Highlight;
|
|
607
|
+
}
|
|
608
|
+
.arap-skip-to-main:focus,
|
|
609
|
+
.arap-skip-to-main:focus-visible {
|
|
610
|
+
outline: 3px solid Highlight;
|
|
611
|
+
}
|
|
612
|
+
}
|
|
559
613
|
@media (max-height: 480px) {
|
|
560
614
|
.arap-root .arap-panel {
|
|
561
615
|
top: max(16px, env(safe-area-inset-top)) !important;
|
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`, `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`, `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`.
|
|
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`.
|
|
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`.
|
|
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`.
|
|
56
56
|
|
|
57
57
|
Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
|
|
58
58
|
|
|
@@ -86,7 +86,7 @@ completed. Closing a child issue does not replace the milestone exit review.
|
|
|
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
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
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.
|
|
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.
|
package/docs/FEATURES.md
CHANGED
|
@@ -15,6 +15,9 @@ All features are opt-in via controllers, use native buttons, support Enter/Space
|
|
|
15
15
|
| SaturationController / saturation | 0; 0/1/2 | Off, 0.2×, 2× saturation. Composes with other filters. |
|
|
16
16
|
| InvertColorsController / invertColors | false; boolean | Adds invert(1), includes content images. |
|
|
17
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. |
|
|
18
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. |
|
|
19
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. |
|
|
20
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. |
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Link Highlighting, Focus Visibility, and Landmark Skip Links
|
|
2
|
+
|
|
3
|
+
This document outlines the architecture, WCAG 2.2 alignment, and behavioral guarantees for link highlighting, focus visibility, and the skip-to-main landmark link implemented under **[A11Y-205]**.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Non-Color-Only Link Highlighting
|
|
8
|
+
|
|
9
|
+
### The Problem
|
|
10
|
+
|
|
11
|
+
WCAG SC 1.4.1 (Use of Color) requires that color is not used as the sole visual means of conveying information or distinguishing interactive elements. Many websites style hyperlinks with custom colors that lack underlines or sufficient contrast against surrounding text.
|
|
12
|
+
|
|
13
|
+
### Implementation
|
|
14
|
+
|
|
15
|
+
- **Non-Color Cues**: Active link highlighting applies an unmistakable visual underline:
|
|
16
|
+
```css
|
|
17
|
+
text-decoration: underline !important;
|
|
18
|
+
text-decoration-thickness: 2px !important;
|
|
19
|
+
text-underline-offset: 3px !important;
|
|
20
|
+
```
|
|
21
|
+
- **High-Contrast Palettes**: Users can select high-contrast badge/background styles (`yellow-on-black`, `blue-on-yellow`, `black-on-white`), or standard high-contrast underlining.
|
|
22
|
+
- **Forced-Colors Support**: Under Windows High Contrast Mode or `@media (forced-colors: active)`, links preserve the operating system's `LinkText` system keyword without conflicting hardcoded backgrounds.
|
|
23
|
+
- **Disabled Semantics Preservation**: Inactive, unlinked, or disabled anchors (`a:not([href])`, `a[aria-disabled="true"]`, `a.disabled`) are explicitly skipped, ensuring screen reader and keyboard users are not misled into attempting navigation on disabled links.
|
|
24
|
+
- **Widget Boundary Protection**: Elements matching `[data-arap-ui] *` are excluded from host mutations.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 2. Enhanced Focus Visibility (`HighlightFocusController`)
|
|
29
|
+
|
|
30
|
+
### The Problem
|
|
31
|
+
|
|
32
|
+
WCAG SC 2.4.7 (Focus Visible) and SC 2.4.11 (Focus Appearance - AAA) require clear, high-contrast visual indicators for keyboard navigation. Native browser focus rings often disappear against complex backgrounds or are suppressed by host stylesheets (`outline: none`).
|
|
33
|
+
|
|
34
|
+
### Implementation
|
|
35
|
+
|
|
36
|
+
- **Dual-Ring High Contrast**: When enabled, an accessible high-contrast outline is applied to all active interactive controls (`button`, `a`, `input`, `select`, `textarea`, `[tabindex]`):
|
|
37
|
+
```css
|
|
38
|
+
*:not([data-arap-ui]):not([data-arap-ui] *):focus-visible {
|
|
39
|
+
outline: 3px solid #2563eb !important;
|
|
40
|
+
outline-offset: 3px !important;
|
|
41
|
+
box-shadow: 0 0 0 5px rgba(255, 255, 255, 0.9) !important;
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
The primary 3px blue ring coupled with the outer 5px white halo ensures visibility on both light and dark backgrounds.
|
|
45
|
+
- **Forced-Colors Mode**: Under `@media (forced-colors: active)`, the ring yields to the system `Highlight` keyword with `box-shadow: none`, adhering to the active OS high-contrast theme.
|
|
46
|
+
- **Disabled Semantics**: Disabled elements (`*:disabled:focus-visible`, `*[aria-disabled="true"]:focus-visible`) have outlines suppressed (`outline: none !important`), preventing disabled controls from showing active focus rings.
|
|
47
|
+
- **Clean Teardown**: Upon reset or disabling, the injected style element is immediately removed, restoring host and UA defaults.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. Authentic Skip-To-Main Landmark Link (`SkipToMainLink`)
|
|
52
|
+
|
|
53
|
+
### The Problem
|
|
54
|
+
|
|
55
|
+
WCAG SC 2.4.1 (Bypass Blocks) requires a mechanism to bypass repetitive navigation blocks directly to the main content. However, rendering a skip-to-main link when no `<main>` landmark exists results in broken navigation and false promises to assistive technology users.
|
|
56
|
+
|
|
57
|
+
### Implementation
|
|
58
|
+
|
|
59
|
+
- **Authentic Landmark Verification**: `findMainLandmark()` checks for a valid native `<main>` element or element with explicit `role="main"`.
|
|
60
|
+
- **Conditional Rendering**: `SkipToMainLink` renders **only when an authentic main landmark exists**. If no landmark is found, it renders `null`.
|
|
61
|
+
- **Dynamic Mutation Handling**: Uses `useSyncExternalStore` to monitor DOM mutations via `MutationObserver`. If a client-side route transition inserts or removes a `<main>` element, the skip link updates automatically without unnecessary re-renders.
|
|
62
|
+
- **Accessible Interaction**:
|
|
63
|
+
- Hidden off-screen using `clip-path: inset(50%)` until focused via keyboard Tab.
|
|
64
|
+
- On focus, slides into the top-left viewport meeting the minimum 44px touch/click target size.
|
|
65
|
+
- On activation, assigns `tabindex="-1"` if needed, programmatically transfers focus to the landmark, and smoothly scrolls it into view.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "accessibility-plugin-react",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.8.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",
|