accessibility-plugin-react 2.13.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 -22
- package/dist/index.d.mts +224 -1
- package/dist/index.d.ts +224 -1
- package/dist/index.js +2282 -345
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2255 -349
- package/dist/index.mjs.map +1 -1
- package/dist/style.css +312 -0
- package/docs/API.md +6 -3
- package/docs/BUILD_AND_RELEASE_PLAN.md +3 -3
- package/docs/FEATURES.md +29 -26
- package/docs/PAGE_NAVIGATOR.md +90 -0
- package/docs/PRESETS.md +134 -0
- package/docs/PROFILES.md +113 -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/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",
|