accessibility-plugin-react 2.12.0 → 2.16.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 +25 -21
- package/dist/index.d.mts +245 -1
- package/dist/index.d.ts +245 -1
- package/dist/index.js +2585 -304
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2550 -305
- package/dist/index.mjs.map +1 -1
- package/dist/style.css +366 -0
- package/docs/API.md +6 -3
- package/docs/BUILD_AND_RELEASE_PLAN.md +4 -4
- package/docs/FEATURES.md +29 -25
- package/docs/PAGE_NAVIGATOR.md +90 -0
- package/docs/PRESETS.md +134 -0
- package/docs/PROFILES.md +113 -0
- package/docs/TOOLTIPS.md +102 -0
- package/package.json +1 -1
package/docs/PRESETS.md
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Custom Saved Presets and Settings Import/Export (A11Y-305)
|
|
2
|
+
|
|
3
|
+
The `accessibility-plugin-react` library includes user-editable custom presets and versioned JSON backup and transfer capabilities. Users can save their preferred combination of accessibility preferences under a meaningful name, re-apply them with a single click, and export or import them across browsers and devices.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Core Principles & Guardrails
|
|
8
|
+
|
|
9
|
+
- **Privacy Exclusions**: Presets and exported JSON files contain **only** validated accessibility settings. Private personal data, page contents, form inputs, session tokens, user credentials, transcripts, and recordings are **strictly excluded**.
|
|
10
|
+
- **Deterministic Storage & Reset Survival**: Custom presets are preserved across "Reset All" display resets. While display reset restores visual features to their initial values, the user's saved preset library remains intact unless individually deleted.
|
|
11
|
+
- **Stable IDs**: Each preset receives a persistent, stable identifier (`preset_<timestamp>_<random>`) that is retained during import and deduplicated upon merging.
|
|
12
|
+
- **Versioned Envelope**: Presets are exported in a standard, versioned envelope (`version: 1`) with schema references, export timestamps, and application identity.
|
|
13
|
+
- **Robust Error Handling**: Imports strictly validate incoming data, accepting valid v1 envelopes, legacy arrays, and flat settings objects, while returning clear, descriptive user-facing errors on syntax issues or unsupported future versions.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 2. Versioned JSON Schema (v1)
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"$schema": "https://accessibility-plugin.org/schemas/presets-v1.json",
|
|
22
|
+
"version": 1,
|
|
23
|
+
"app": "accessibility-plugin-react",
|
|
24
|
+
"exportedAt": "2026-10-27T08:00:00.000Z",
|
|
25
|
+
"presets": [
|
|
26
|
+
{
|
|
27
|
+
"id": "preset_1730000000000_a1b2c3",
|
|
28
|
+
"name": "Evening Low Strain",
|
|
29
|
+
"createdAt": "2026-10-27T08:00:00.000Z",
|
|
30
|
+
"settings": {
|
|
31
|
+
"fontScale": 1.25,
|
|
32
|
+
"lineHeight": 1.5,
|
|
33
|
+
"contrastMode": "dark",
|
|
34
|
+
"reduceMotion": true,
|
|
35
|
+
"highlightLinks": true
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
],
|
|
39
|
+
"currentSettings": {
|
|
40
|
+
"contrastMode": "dark",
|
|
41
|
+
"fontScale": 1.25
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## 3. Supported Import Formats
|
|
49
|
+
|
|
50
|
+
| Format | Structure | Behavior |
|
|
51
|
+
| ------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
52
|
+
| **Version 1 Envelope** | Object with `version: 1`, `presets: [...]`, and optional `currentSettings` | Validates schema, imports presets (deduped by ID), and applies current settings if present. |
|
|
53
|
+
| **Legacy Preset Array** | Array of objects `[{ id, name, settings }, ...]` | Automatically migrates into valid presets, generating IDs and timestamps if missing. |
|
|
54
|
+
| **Flat Settings Object** | Object with key-value preferences `{ fontScale: 1.2, contrastMode: "high" }` | Applies settings to active feature store as imported settings. |
|
|
55
|
+
| **Unsupported Version** | Object with `version > 1` | Rejects with clear message: _"Unsupported schema version: version X is newer than supported version 1."_ |
|
|
56
|
+
| **Malformed JSON** | Invalid syntax or non-object content | Rejects with syntax error message without corrupting state or store. |
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 4. Components & Hooks
|
|
61
|
+
|
|
62
|
+
### `<PresetsController />`
|
|
63
|
+
|
|
64
|
+
Renders an accessible custom preset manager inside the widget list:
|
|
65
|
+
|
|
66
|
+
- Save current configuration as a new named preset.
|
|
67
|
+
- Browse saved presets with affected settings summary chips.
|
|
68
|
+
- 1-click **Apply** and **Delete** actions.
|
|
69
|
+
- **Export JSON** to download a backup file.
|
|
70
|
+
- **Import JSON** file picker supporting `.json` files.
|
|
71
|
+
- Live announcements with `role="status"` and `aria-live="polite"` for screen readers.
|
|
72
|
+
|
|
73
|
+
Aliases:
|
|
74
|
+
|
|
75
|
+
- `CustomPresetsController`
|
|
76
|
+
- `SettingsImportExportController`
|
|
77
|
+
- `PresetsBackupController`
|
|
78
|
+
|
|
79
|
+
```tsx
|
|
80
|
+
import {
|
|
81
|
+
AccessibilityPlugin,
|
|
82
|
+
AccessibilityButton,
|
|
83
|
+
AccessibilityList,
|
|
84
|
+
PresetsController,
|
|
85
|
+
} from "accessibility-plugin-react";
|
|
86
|
+
|
|
87
|
+
export function App() {
|
|
88
|
+
return (
|
|
89
|
+
<AccessibilityPlugin>
|
|
90
|
+
<AccessibilityButton />
|
|
91
|
+
<AccessibilityList>
|
|
92
|
+
<PresetsController />
|
|
93
|
+
</AccessibilityList>
|
|
94
|
+
</AccessibilityPlugin>
|
|
95
|
+
);
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### `usePresets()` Hook
|
|
100
|
+
|
|
101
|
+
Headless hook to interact with presets and import/export programmatically:
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
import { usePresets } from "accessibility-plugin-react";
|
|
105
|
+
|
|
106
|
+
function CustomPresetUI() {
|
|
107
|
+
const {
|
|
108
|
+
presets,
|
|
109
|
+
saveCurrentAsPreset,
|
|
110
|
+
applyPreset,
|
|
111
|
+
deletePreset,
|
|
112
|
+
downloadExport,
|
|
113
|
+
importFromFile,
|
|
114
|
+
} = usePresets();
|
|
115
|
+
|
|
116
|
+
return (
|
|
117
|
+
<div>
|
|
118
|
+
<button onClick={() => saveCurrentAsPreset("My Custom Setup")}>
|
|
119
|
+
Save Preset
|
|
120
|
+
</button>
|
|
121
|
+
<button onClick={() => downloadExport()}>Export Backup</button>
|
|
122
|
+
<ul>
|
|
123
|
+
{presets.map((p) => (
|
|
124
|
+
<li key={p.id}>
|
|
125
|
+
<span>{p.name}</span>
|
|
126
|
+
<button onClick={() => applyPreset(p.id)}>Apply</button>
|
|
127
|
+
<button onClick={() => deletePreset(p.id)}>Delete</button>
|
|
128
|
+
</li>
|
|
129
|
+
))}
|
|
130
|
+
</ul>
|
|
131
|
+
</div>
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
```
|
package/docs/PROFILES.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Accessibility Profiles and Deterministic Override Model
|
|
2
|
+
|
|
3
|
+
`accessibility-plugin-react` provides eight neutral, user-editable accessibility profile presets alongside a deterministic override model. The profiles offer tested suggestions of preference combinations without making medical claims or altering keyboard navigation.
|
|
4
|
+
|
|
5
|
+
## The Eight Presets
|
|
6
|
+
|
|
7
|
+
Each profile is defined in `src/core/preferences/defaults.ts` and exposed through `PROFILE_DEFINITIONS`:
|
|
8
|
+
|
|
9
|
+
| Profile Preset | Identifier | Description & Focus | Settings Applied |
|
|
10
|
+
| ------------------------- | ------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
11
|
+
| **Motor Impaired** | `motor` | Enhanced focus rings, richer tooltips, and reduced motion. | `highlightFocus: true`, `reduceMotion: true`, `tooltips: true` |
|
|
12
|
+
| **Blind & Screen Reader** | `blind` | Semantic assistance and accessible authored descriptions without speech synthesis or mic requests. | `tooltips: true` |
|
|
13
|
+
| **Color Blind** | `color-blind` | High contrast accents and non-color-only link indicators. | `contrastMode: "high"`, `highlightLinks: true` |
|
|
14
|
+
| **Dyslexia Friendly** | `dyslexia` | Legible typeface, reading guide line, and reduced motion. | `fontFamily: "dyslexia-option"`, `readerMode: "guide"`, `reduceMotion: true` |
|
|
15
|
+
| **Low Vision** | `low-vision` | Enlarged text, large cursor pointer, and high-visibility focus. | `fontScale: 1.25`, `cursorSize: "large"`, `highlightFocus: true`, `tooltips: true` |
|
|
16
|
+
| **Cognitive & Learning** | `cognitive` | Mild text scaling, reading guide line, and distraction reduction. | `fontScale: 1.125`, `readerMode: "guide"`, `reduceMotion: true`, `tooltips: true` |
|
|
17
|
+
| **Seizure & Epileptic** | `seizure` | Pauses nonessential motion and reduces transition flashes. | `reduceMotion: true` |
|
|
18
|
+
| **ADHD / Focus** | `adhd` | Reading mask spotlight and reduced animation distraction. | `readerMode: "mask"`, `reduceMotion: true` |
|
|
19
|
+
|
|
20
|
+
## Deterministic Override Model
|
|
21
|
+
|
|
22
|
+
When a user applies a profile, their pre-existing customizations are never permanently overwritten. The model operates in three distinct layers:
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
┌────────────────────────────────────────────────────────┐
|
|
26
|
+
│ 1. User Explicit Overrides (Highest Precedence) │
|
|
27
|
+
│ Any adjustment made while a profile is active. │
|
|
28
|
+
├────────────────────────────────────────────────────────┤
|
|
29
|
+
│ 2. Active Profile Snapshot (Atomic Suggestion) │
|
|
30
|
+
│ Settings configured by the selected profile preset. │
|
|
31
|
+
├────────────────────────────────────────────────────────┤
|
|
32
|
+
│ 3. Baseline Preferences (Pre-Profile Custom Settings) │
|
|
33
|
+
│ Settings configured by the user prior to profile. │
|
|
34
|
+
└────────────────────────────────────────────────────────┘
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Independent Choice Survival
|
|
38
|
+
|
|
39
|
+
- **Snapshotting**: Upon applying a profile, the pre-profile values for all affected settings are recorded in `baseSnapshot`.
|
|
40
|
+
- **Override Tracking**: When a user adjusts any setting while a profile is active, that setting is stored in `overrides`.
|
|
41
|
+
- **Reversion**: When the user clicks **Revert to custom settings**:
|
|
42
|
+
- Settings that were **not** touched by the user return to their pre-profile `baseSnapshot` values.
|
|
43
|
+
- Settings that **were** explicitly overridden by the user **survive** at their adjusted values.
|
|
44
|
+
- The active profile is cleared to `null`.
|
|
45
|
+
|
|
46
|
+
## Privacy & Safety Guardrails
|
|
47
|
+
|
|
48
|
+
- **Zero Implicit Speech or Microphone Access**: Presets (such as `blind`) strictly provide DOM visual/structural enhancements and never invoke Web Speech API synthesis, microphone permissions, or external audio streams without explicit user consent.
|
|
49
|
+
- **No Medical Efficacy Claims**: Profiles are presented neutrally as assistive suggestions, not diagnostic or therapeutic solutions.
|
|
50
|
+
- **No Keyboard Sequence Mutation**: Profiles never alter standard DOM tab order or create false modal traps.
|
|
51
|
+
|
|
52
|
+
## Component & Hook Usage
|
|
53
|
+
|
|
54
|
+
### Controller Component
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
import {
|
|
58
|
+
AccessibilityPlugin,
|
|
59
|
+
AccessibilityButton,
|
|
60
|
+
AccessibilityList,
|
|
61
|
+
ProfilesController,
|
|
62
|
+
FontSizeController,
|
|
63
|
+
ContrastModeController,
|
|
64
|
+
} from "accessibility-plugin-react";
|
|
65
|
+
|
|
66
|
+
export function Settings() {
|
|
67
|
+
return (
|
|
68
|
+
<AccessibilityPlugin>
|
|
69
|
+
<AccessibilityButton />
|
|
70
|
+
<AccessibilityList>
|
|
71
|
+
<ProfilesController label="Profiles" />
|
|
72
|
+
<FontSizeController />
|
|
73
|
+
<ContrastModeController />
|
|
74
|
+
</AccessibilityList>
|
|
75
|
+
</AccessibilityPlugin>
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Aliases: `ProfileController`, `AccessibilityProfilesController`.
|
|
81
|
+
|
|
82
|
+
### Custom Profile Consumption via `useProfiles()`
|
|
83
|
+
|
|
84
|
+
```tsx
|
|
85
|
+
import { useProfiles } from "accessibility-plugin-react";
|
|
86
|
+
|
|
87
|
+
export function CustomProfileSelector() {
|
|
88
|
+
const {
|
|
89
|
+
profiles,
|
|
90
|
+
activeProfileId,
|
|
91
|
+
activeProfile,
|
|
92
|
+
applyProfile,
|
|
93
|
+
revertProfile,
|
|
94
|
+
isProfileActive,
|
|
95
|
+
} = useProfiles();
|
|
96
|
+
|
|
97
|
+
return (
|
|
98
|
+
<div>
|
|
99
|
+
{profiles.map((p) => (
|
|
100
|
+
<button
|
|
101
|
+
key={p.id}
|
|
102
|
+
onClick={() =>
|
|
103
|
+
isProfileActive(p.id) ? revertProfile() : applyProfile(p.id)
|
|
104
|
+
}
|
|
105
|
+
aria-pressed={isProfileActive(p.id)}
|
|
106
|
+
>
|
|
107
|
+
{p.label} {isProfileActive(p.id) ? "(Active)" : ""}
|
|
108
|
+
</button>
|
|
109
|
+
))}
|
|
110
|
+
</div>
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
```
|
package/docs/TOOLTIPS.md
ADDED
|
@@ -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.
|
|
3
|
+
"version": "2.16.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",
|