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/dist/style.css
CHANGED
|
@@ -1175,3 +1175,315 @@
|
|
|
1175
1175
|
box-shadow: none !important;
|
|
1176
1176
|
}
|
|
1177
1177
|
}
|
|
1178
|
+
|
|
1179
|
+
/* Page Headings and Landmarks Navigator (A11Y-303) */
|
|
1180
|
+
.arap-navigator-dialog {
|
|
1181
|
+
display: flex;
|
|
1182
|
+
flex-direction: column;
|
|
1183
|
+
gap: 8px;
|
|
1184
|
+
width: 100%;
|
|
1185
|
+
margin-top: 10px;
|
|
1186
|
+
padding: 10px;
|
|
1187
|
+
background: var(--arap-control, #f1f5f9);
|
|
1188
|
+
border: 1px solid var(--arap-border, #e2e8f0);
|
|
1189
|
+
border-radius: 8px;
|
|
1190
|
+
box-sizing: border-box;
|
|
1191
|
+
}
|
|
1192
|
+
|
|
1193
|
+
.arap-navigator-tabs {
|
|
1194
|
+
display: flex;
|
|
1195
|
+
gap: 4px;
|
|
1196
|
+
border-bottom: 1px solid var(--arap-border, #cbd5e1);
|
|
1197
|
+
padding-bottom: 6px;
|
|
1198
|
+
}
|
|
1199
|
+
|
|
1200
|
+
.arap-navigator-tab {
|
|
1201
|
+
flex: 1;
|
|
1202
|
+
display: inline-flex;
|
|
1203
|
+
align-items: center;
|
|
1204
|
+
justify-content: center;
|
|
1205
|
+
gap: 6px;
|
|
1206
|
+
padding: 6px 10px;
|
|
1207
|
+
font-size: 12px;
|
|
1208
|
+
font-weight: 600;
|
|
1209
|
+
color: var(--arap-muted, #64748b);
|
|
1210
|
+
background: transparent;
|
|
1211
|
+
border: none;
|
|
1212
|
+
border-radius: 6px;
|
|
1213
|
+
cursor: pointer;
|
|
1214
|
+
transition: all 120ms ease;
|
|
1215
|
+
}
|
|
1216
|
+
|
|
1217
|
+
.arap-navigator-tab:hover {
|
|
1218
|
+
color: var(--arap-text, #0f172a);
|
|
1219
|
+
background: rgba(0, 0, 0, 0.04);
|
|
1220
|
+
}
|
|
1221
|
+
|
|
1222
|
+
.arap-navigator-tab-active {
|
|
1223
|
+
color: var(--arap-accent, #008060) !important;
|
|
1224
|
+
background: var(--arap-selected, #f0fdf4) !important;
|
|
1225
|
+
}
|
|
1226
|
+
|
|
1227
|
+
.arap-navigator-search-box {
|
|
1228
|
+
width: 100%;
|
|
1229
|
+
}
|
|
1230
|
+
|
|
1231
|
+
.arap-navigator-search {
|
|
1232
|
+
width: 100%;
|
|
1233
|
+
box-sizing: border-box;
|
|
1234
|
+
padding: 6px 10px;
|
|
1235
|
+
font-size: 12px;
|
|
1236
|
+
border: 1px solid var(--arap-border, #cbd5e1);
|
|
1237
|
+
border-radius: 6px;
|
|
1238
|
+
background: var(--arap-surface, #ffffff);
|
|
1239
|
+
color: var(--arap-text, #0f172a);
|
|
1240
|
+
}
|
|
1241
|
+
|
|
1242
|
+
.arap-navigator-search:focus {
|
|
1243
|
+
outline: 2px solid var(--arap-accent, #008060);
|
|
1244
|
+
outline-offset: 1px;
|
|
1245
|
+
}
|
|
1246
|
+
|
|
1247
|
+
.arap-navigator-content {
|
|
1248
|
+
max-height: 240px;
|
|
1249
|
+
overflow-y: auto;
|
|
1250
|
+
overflow-x: hidden;
|
|
1251
|
+
}
|
|
1252
|
+
|
|
1253
|
+
.arap-navigator-list {
|
|
1254
|
+
list-style: none;
|
|
1255
|
+
margin: 0;
|
|
1256
|
+
padding: 0;
|
|
1257
|
+
display: flex;
|
|
1258
|
+
flex-direction: column;
|
|
1259
|
+
gap: 4px;
|
|
1260
|
+
}
|
|
1261
|
+
|
|
1262
|
+
.arap-navigator-item {
|
|
1263
|
+
margin: 0;
|
|
1264
|
+
padding: 0;
|
|
1265
|
+
}
|
|
1266
|
+
|
|
1267
|
+
.arap-navigator-jump-btn {
|
|
1268
|
+
width: 100%;
|
|
1269
|
+
box-sizing: border-box;
|
|
1270
|
+
display: flex;
|
|
1271
|
+
align-items: center;
|
|
1272
|
+
gap: 8px;
|
|
1273
|
+
padding: 6px 8px;
|
|
1274
|
+
font-size: 12px;
|
|
1275
|
+
font-weight: 500;
|
|
1276
|
+
text-align: left;
|
|
1277
|
+
background: var(--arap-surface, #ffffff);
|
|
1278
|
+
border: 1px solid var(--arap-border, #e2e8f0);
|
|
1279
|
+
border-radius: 6px;
|
|
1280
|
+
color: var(--arap-text, #0f172a);
|
|
1281
|
+
cursor: pointer;
|
|
1282
|
+
transition:
|
|
1283
|
+
background 100ms ease,
|
|
1284
|
+
border-color 100ms ease;
|
|
1285
|
+
}
|
|
1286
|
+
|
|
1287
|
+
.arap-navigator-jump-btn:hover,
|
|
1288
|
+
.arap-navigator-jump-btn:focus-visible {
|
|
1289
|
+
background: var(--arap-selected, #f0fdf4);
|
|
1290
|
+
border-color: var(--arap-accent, #008060);
|
|
1291
|
+
outline: 2px solid var(--arap-accent, #008060);
|
|
1292
|
+
outline-offset: -1px;
|
|
1293
|
+
}
|
|
1294
|
+
|
|
1295
|
+
.arap-navigator-badge {
|
|
1296
|
+
display: inline-block;
|
|
1297
|
+
padding: 2px 6px;
|
|
1298
|
+
font-size: 10px;
|
|
1299
|
+
font-weight: 700;
|
|
1300
|
+
border-radius: 4px;
|
|
1301
|
+
flex-shrink: 0;
|
|
1302
|
+
}
|
|
1303
|
+
|
|
1304
|
+
.arap-navigator-badge-h {
|
|
1305
|
+
background: #e0f2fe;
|
|
1306
|
+
color: #0369a1;
|
|
1307
|
+
}
|
|
1308
|
+
|
|
1309
|
+
.arap-navigator-badge-l {
|
|
1310
|
+
background: #fef3c7;
|
|
1311
|
+
color: #b45309;
|
|
1312
|
+
}
|
|
1313
|
+
|
|
1314
|
+
.arap-navigator-item-text {
|
|
1315
|
+
overflow: hidden;
|
|
1316
|
+
text-overflow: ellipsis;
|
|
1317
|
+
white-space: nowrap;
|
|
1318
|
+
}
|
|
1319
|
+
|
|
1320
|
+
.arap-navigator-empty {
|
|
1321
|
+
padding: 16px;
|
|
1322
|
+
font-size: 12px;
|
|
1323
|
+
text-align: center;
|
|
1324
|
+
color: var(--arap-muted, #64748b);
|
|
1325
|
+
font-style: italic;
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1328
|
+
/* Accessibility Profiles and Preview Cards (A11Y-304) */
|
|
1329
|
+
.arap-profile-card {
|
|
1330
|
+
padding: 12px;
|
|
1331
|
+
border: 1px solid var(--arap-border, #e2e8f0);
|
|
1332
|
+
border-radius: 8px;
|
|
1333
|
+
background: var(--arap-card-bg, #ffffff);
|
|
1334
|
+
transition:
|
|
1335
|
+
border-color 0.15s ease,
|
|
1336
|
+
box-shadow 0.15s ease;
|
|
1337
|
+
}
|
|
1338
|
+
|
|
1339
|
+
.arap-profile-card:hover {
|
|
1340
|
+
border-color: var(--arap-primary, #2563eb);
|
|
1341
|
+
}
|
|
1342
|
+
|
|
1343
|
+
.arap-profile-card-active {
|
|
1344
|
+
border-color: var(--arap-primary, #2563eb);
|
|
1345
|
+
background: rgba(37, 99, 235, 0.03);
|
|
1346
|
+
box-shadow: 0 0 0 1px var(--arap-primary, #2563eb);
|
|
1347
|
+
}
|
|
1348
|
+
|
|
1349
|
+
.arap-profile-header {
|
|
1350
|
+
margin-bottom: 8px;
|
|
1351
|
+
}
|
|
1352
|
+
|
|
1353
|
+
.arap-profile-title-row {
|
|
1354
|
+
display: flex;
|
|
1355
|
+
align-items: center;
|
|
1356
|
+
justify-content: space-between;
|
|
1357
|
+
margin-bottom: 4px;
|
|
1358
|
+
}
|
|
1359
|
+
|
|
1360
|
+
.arap-profile-title {
|
|
1361
|
+
margin: 0;
|
|
1362
|
+
font-size: 13px;
|
|
1363
|
+
font-weight: 600;
|
|
1364
|
+
color: var(--arap-text, #1e293b);
|
|
1365
|
+
}
|
|
1366
|
+
|
|
1367
|
+
.arap-profile-active-badge {
|
|
1368
|
+
display: inline-block;
|
|
1369
|
+
padding: 2px 8px;
|
|
1370
|
+
font-size: 11px;
|
|
1371
|
+
font-weight: 600;
|
|
1372
|
+
border-radius: 9999px;
|
|
1373
|
+
background: #dbeafe;
|
|
1374
|
+
color: #1d4ed8;
|
|
1375
|
+
}
|
|
1376
|
+
|
|
1377
|
+
.arap-profile-desc {
|
|
1378
|
+
margin: 0;
|
|
1379
|
+
font-size: 11px;
|
|
1380
|
+
color: var(--arap-muted, #64748b);
|
|
1381
|
+
line-height: 1.4;
|
|
1382
|
+
}
|
|
1383
|
+
|
|
1384
|
+
.arap-profile-affected {
|
|
1385
|
+
margin-top: 8px;
|
|
1386
|
+
margin-bottom: 10px;
|
|
1387
|
+
}
|
|
1388
|
+
|
|
1389
|
+
.arap-profile-affected-label {
|
|
1390
|
+
display: block;
|
|
1391
|
+
font-size: 10px;
|
|
1392
|
+
font-weight: 600;
|
|
1393
|
+
text-transform: uppercase;
|
|
1394
|
+
letter-spacing: 0.05em;
|
|
1395
|
+
color: var(--arap-muted, #94a3b8);
|
|
1396
|
+
margin-bottom: 4px;
|
|
1397
|
+
}
|
|
1398
|
+
|
|
1399
|
+
.arap-profile-chips {
|
|
1400
|
+
display: flex;
|
|
1401
|
+
flex-wrap: wrap;
|
|
1402
|
+
gap: 4px;
|
|
1403
|
+
}
|
|
1404
|
+
|
|
1405
|
+
.arap-profile-chip {
|
|
1406
|
+
display: inline-block;
|
|
1407
|
+
padding: 2px 6px;
|
|
1408
|
+
font-size: 10px;
|
|
1409
|
+
background: var(--arap-chip-bg, #f1f5f9);
|
|
1410
|
+
color: var(--arap-text, #334155);
|
|
1411
|
+
border-radius: 4px;
|
|
1412
|
+
border: 1px solid var(--arap-chip-border, #e2e8f0);
|
|
1413
|
+
}
|
|
1414
|
+
|
|
1415
|
+
.arap-profile-actions {
|
|
1416
|
+
display: flex;
|
|
1417
|
+
justify-content: flex-end;
|
|
1418
|
+
margin-top: 8px;
|
|
1419
|
+
}
|
|
1420
|
+
|
|
1421
|
+
.arap-profile-apply-btn,
|
|
1422
|
+
.arap-profile-revert-btn {
|
|
1423
|
+
display: inline-flex;
|
|
1424
|
+
align-items: center;
|
|
1425
|
+
justify-content: center;
|
|
1426
|
+
min-height: 36px;
|
|
1427
|
+
padding: 6px 14px;
|
|
1428
|
+
font-size: 12px;
|
|
1429
|
+
font-weight: 600;
|
|
1430
|
+
border-radius: 6px;
|
|
1431
|
+
cursor: pointer;
|
|
1432
|
+
transition:
|
|
1433
|
+
background 0.15s ease,
|
|
1434
|
+
border-color 0.15s ease;
|
|
1435
|
+
}
|
|
1436
|
+
|
|
1437
|
+
.arap-profile-apply-btn {
|
|
1438
|
+
background: var(--arap-primary, #2563eb);
|
|
1439
|
+
color: #ffffff;
|
|
1440
|
+
border: 1px solid var(--arap-primary, #2563eb);
|
|
1441
|
+
}
|
|
1442
|
+
|
|
1443
|
+
.arap-profile-apply-btn:hover {
|
|
1444
|
+
background: #1d4ed8;
|
|
1445
|
+
}
|
|
1446
|
+
|
|
1447
|
+
.arap-profile-revert-btn {
|
|
1448
|
+
background: #ffffff;
|
|
1449
|
+
color: #dc2626;
|
|
1450
|
+
border: 1px solid #fca5a5;
|
|
1451
|
+
}
|
|
1452
|
+
|
|
1453
|
+
.arap-profile-revert-btn:hover {
|
|
1454
|
+
background: #fef2f2;
|
|
1455
|
+
border-color: #f87171;
|
|
1456
|
+
}
|
|
1457
|
+
|
|
1458
|
+
.arap-large-controls .arap-profile-apply-btn,
|
|
1459
|
+
.arap-large-controls .arap-profile-revert-btn {
|
|
1460
|
+
min-height: 48px;
|
|
1461
|
+
padding: 10px 18px;
|
|
1462
|
+
font-size: 14px;
|
|
1463
|
+
}
|
|
1464
|
+
|
|
1465
|
+
@media (prefers-reduced-motion: reduce) {
|
|
1466
|
+
.arap-profile-card,
|
|
1467
|
+
.arap-profile-apply-btn,
|
|
1468
|
+
.arap-profile-revert-btn,
|
|
1469
|
+
.arap-preset-card {
|
|
1470
|
+
transition: none !important;
|
|
1471
|
+
}
|
|
1472
|
+
}
|
|
1473
|
+
|
|
1474
|
+
/* Custom Presets and Transfer (A11Y-305) */
|
|
1475
|
+
.arap-preset-card {
|
|
1476
|
+
transition:
|
|
1477
|
+
border-color 0.15s ease,
|
|
1478
|
+
box-shadow 0.15s ease;
|
|
1479
|
+
}
|
|
1480
|
+
|
|
1481
|
+
.arap-preset-card:hover {
|
|
1482
|
+
border-color: var(--arap-border-hover, #cbd5e1);
|
|
1483
|
+
}
|
|
1484
|
+
|
|
1485
|
+
.arap-large-controls .arap-preset-card button {
|
|
1486
|
+
min-height: 48px;
|
|
1487
|
+
padding: 10px 16px;
|
|
1488
|
+
font-size: 14px;
|
|
1489
|
+
}
|
package/docs/API.md
CHANGED
|
@@ -20,6 +20,9 @@ All exports are named from `accessibility-plugin-react`. JavaScript consumers re
|
|
|
20
20
|
| LetterSpacingController | Optional `min`, `max`, `step`, `steps`. Excludes tables and code blocks; respects language-aware limits (disables on cursive/Arabic, clamps <=1px on Indic/Sinhala/Tamil). |
|
|
21
21
|
| WordSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–10px, step 1). Excludes tables, code blocks, controls, and widget UI. |
|
|
22
22
|
| ParagraphSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–32px, step 4). Increases bottom margin on `p` and `[role="paragraph"]`. |
|
|
23
|
+
| PageNavigatorController | Optional `title?: string`, `headingsLabel?: string`, `landmarksLabel?: string`, `searchPlaceholder?: string`, `largeControls?: boolean`. Interactive headings and landmarks navigator with safe focus and live updates. Aliases: `HeadingsNavigatorController`, `PageStructureController`. See docs/PAGE_NAVIGATOR.md. |
|
|
24
|
+
| ProfilesController | Optional `label?: string`, `description?: string`, `largeControls?: boolean`, `onProfileChange?: (id) => void`. Previews, applies, and reverts eight neutral presets with deterministic override model. Aliases: `ProfileController`, `AccessibilityProfilesController`. See docs/PROFILES.md. |
|
|
25
|
+
| PresetsController | Optional `className?: string`, `label?: string`, `description?: string`, `largeControls?: boolean`. Saves named custom presets and handles versioned JSON import/export with privacy exclusions. Aliases: `CustomPresetsController`, `SettingsImportExportController`, `PresetsBackupController`. See docs/PRESETS.md. |
|
|
23
26
|
| All other controllers in FEATURES.md | Pick/omit in JSX. For custom labels or behavior, compose a control with useAccessibility or the modular control primitives. |
|
|
24
27
|
|
|
25
28
|
Use one button/list pair per provider and one provider per document. UI IDs use React `useId`; do not target the old fixed `arap-panel` ID. Plugin children can include ordinary app content, but mounting the widget as a sibling makes intent clearer. Persistence configuration is fixed at mount; use `<AccessibilityPlugin key={newKey} persistenceKey={newKey}>` when switching storage identity.
|
|
@@ -48,11 +51,11 @@ Definitions/defaults are immutable for the provider lifetime; the first register
|
|
|
48
51
|
|
|
49
52
|
`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
53
|
|
|
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`, `BigCursorControllerProps`, `ReadingMaskControllerProps`, `ReadingGuideControllerProps`, `TooltipsControllerProps`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`.
|
|
54
|
+
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`, `BigCursorControllerProps`, `ReadingMaskControllerProps`, `ReadingGuideControllerProps`, `TooltipsControllerProps`, `PageNavigatorControllerProps`, `HeadingItem`, `LandmarkItem`, `ProfilesControllerProps`, `ActiveProfileState`, `UseProfilesResult`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`, `PresetsControllerProps`, `CustomPreset`, `PresetsExportV1`, `ImportResult`, `UsePresetsResult`.
|
|
52
55
|
|
|
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`, `BigCursorController`, `ReadingMaskController`, `ReadingGuideController`, `TooltipsController`, `AccessibleTooltipsController`, `SkipToMainLink`.
|
|
56
|
+
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`, `BigCursorController`, `ReadingMaskController`, `ReadingGuideController`, `TooltipsController`, `AccessibleTooltipsController`, `PageNavigatorController`, `HeadingsNavigatorController`, `PageStructureController`, `ProfilesController`, `ProfileController`, `AccessibilityProfilesController`, `PresetsController`, `CustomPresetsController`, `SettingsImportExportController`, `PresetsBackupController`, `SkipToMainLink`.
|
|
54
57
|
|
|
55
|
-
Exported typography, contrast, reading aids, tooltips, 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`, `hasFinePointer`, `subscribeFinePointer`, `nudgeReadingAid`, `DEFAULT_READING_MASK_HEIGHT`, `MIN_READING_MASK_HEIGHT`, `MAX_READING_MASK_HEIGHT`, `READING_MASK_HEIGHT_PRESETS`, `getAuthoredDescription`, `positionTooltip`, `enableAccessibleTooltips`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`.
|
|
58
|
+
Exported typography, contrast, reading aids, tooltips, 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`, `hasFinePointer`, `subscribeFinePointer`, `nudgeReadingAid`, `DEFAULT_READING_MASK_HEIGHT`, `MIN_READING_MASK_HEIGHT`, `MAX_READING_MASK_HEIGHT`, `READING_MASK_HEIGHT_PRESETS`, `getAuthoredDescription`, `positionTooltip`, `enableAccessibleTooltips`, `scanHeadings`, `scanLandmarks`, `navigateToElement`, `subscribePageStructure`, `useProfiles`, `ALL_PROFILE_IDS`, `getProfileDefinition`, `mapProfileSettingsToFeatures`, `mapFeaturesToProfileSettings`, `applyProfileToStore`, `revertProfileFromStore`, `recordProfileOverride`, `usePresets`, `createCustomPreset`, `isValidCustomPreset`, `exportPresetsToJson`, `downloadJsonFile`, `validateAndParseImport`, `applyCustomPresetToStore`, `sanitizePreferences`, `ALLOWED_PREFERENCE_KEYS`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`.
|
|
56
59
|
|
|
57
60
|
Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
|
|
58
61
|
|
|
@@ -95,9 +95,9 @@ completed. Closing a child issue does not replace the milestone exit review.
|
|
|
95
95
|
|
|
96
96
|
- [x] [A11Y-301 — Cursor enlargement, reading mask and reading guide #49](https://github.com/prabothcharith/accessibility-react/issues/49) — Add capability-aware large cursor, pointer-transparent reading guide and adjustable reading mask with keyboard/touch alternatives and cleanup.
|
|
97
97
|
- [x] [A11Y-302 — Accessible tooltips from authored descriptions #50](https://github.com/prabothcharith/accessibility-react/issues/50) — Show keyboard/pointer tooltips only from authored accessible descriptions, with Escape dismissal, safe positioning and no private-field disclosure.
|
|
98
|
-
- [
|
|
99
|
-
- [
|
|
100
|
-
- [
|
|
98
|
+
- [x] [A11Y-303 — Page headings and landmarks navigator #51](https://github.com/prabothcharith/accessibility-react/issues/51) — Build a read-only headings/landmarks navigator that scrolls and focuses safely, updates dynamic routes and never invents semantics.
|
|
99
|
+
- [x] [A11Y-304 — Eight profiles and deterministic override model #52](https://github.com/prabothcharith/accessibility-react/issues/52) — Implement eight neutral editable profiles with previews, atomic application, explicit override layering and no implicit speech or microphone activation.
|
|
100
|
+
- [x] [A11Y-305 — Custom saved presets and settings import/export #53](https://github.com/prabothcharith/accessibility-react/issues/53) — Add named custom presets and validated versioned JSON import/export that excludes personal content and handles malformed data clearly.
|
|
101
101
|
- [ ] [A11Y-306 — Sinhala and Tamil locale packs with accessibility review #54](https://github.com/prabothcharith/accessibility-react/issues/54) — Add reviewed Sinhala and Tamil widget locale packs and verify glyphs, long labels, search, announcements, fallback and assistive use.
|
|
102
102
|
- [ ] [A11Y-307 — Non-destructive reading mode proof of concept #55](https://github.com/prabothcharith/accessibility-react/issues/55) — Prototype safe article-focused reading mode without rewriting host DOM, losing content, breaking focus or sending content externally.
|
|
103
103
|
- [ ] [A11Y-308 — Keyboard shortcut help, remapping and link explorer #56](https://github.com/prabothcharith/accessibility-react/issues/56) — Add discoverable shortcut and heading-navigation help, collision-safe remapping and link exploration without hijacking browser or host commands.
|
package/docs/FEATURES.md
CHANGED
|
@@ -2,32 +2,35 @@
|
|
|
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
|
|
6
|
-
|
|
|
7
|
-
| TextScaleController / fontScale
|
|
8
|
-
| FontSizeController / fontSize
|
|
9
|
-
| LineHeightController / lineHeight
|
|
10
|
-
| LetterSpacingController / letterSpacing
|
|
11
|
-
| WordSpacingController / wordSpacing
|
|
12
|
-
| ParagraphSpacingController / paragraphSpacing
|
|
13
|
-
| ContrastController / contrast
|
|
14
|
-
| ContrastModeController / contrastMode
|
|
15
|
-
| SaturationController / saturation
|
|
16
|
-
| InvertColorsController / invertColors
|
|
17
|
-
| GrayscaleController / grayscale
|
|
18
|
-
| LinkHighlightController / linkHighlight
|
|
19
|
-
| HighlightFocusController / highlightFocus
|
|
20
|
-
| SkipToMainLink / findMainLandmark
|
|
21
|
-
| TextAlignController / textAlign
|
|
22
|
-
| FontFamilyController / fontFamily
|
|
23
|
-
| HideImagesController / HideDecorativeImagesController / hideImages
|
|
24
|
-
| HideVideosController / hideVideos
|
|
25
|
-
| ReduceMotionController / reduceMotion
|
|
26
|
-
| BigCursorController / bigCursor
|
|
27
|
-
| ReadingMaskController / readingMask
|
|
28
|
-
| ReadingGuideController / readingGuide
|
|
29
|
-
| TooltipsController / AccessibleTooltipsController / tooltips
|
|
30
|
-
|
|
|
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. Capability-aware: detects `(pointer: fine)` and suppresses styles on touch-only hardware. Host CSS cursor effects are restored. See docs/READING_AIDS.md. |
|
|
27
|
+
| ReadingMaskController / readingMask | false; boolean / number (height) | Transparent reading aperture window with surrounding screen dimmed. Adjustable height (default 100px, 40–400px), stepper controls, pointer/touch/focus/scroll tracking, Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
|
|
28
|
+
| ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border. Pointer-transparent (`pointer-events: none !important`), never blocks clicks/selection/focus. Follows pointer, touch drag, keyboard focus, and scroll. Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
|
|
29
|
+
| TooltipsController / AccessibleTooltipsController / tooltips | false; boolean | Displays authored descriptions (`aria-description`, `aria-describedby`, `aria-label`, `alt`, `title`) on hover and focus. Strictly excludes sensitive/password fields. WCAG 2.1 SC 1.4.13 compliant (Escape dismissal, hoverable, persistent, viewport clamped). See docs/TOOLTIPS.md. |
|
|
30
|
+
| PageNavigatorController / HeadingsNavigatorController / PageStructureController | Action dialog; no persistent preference | Scans real DOM headings (`h1`–`h6`) and named landmarks (`banner`, `navigation`, `main`, `region`, etc.). Safe scroll and focus with temporary tabindex cleanup, live mutation updates without loops, and search filtering. See docs/PAGE_NAVIGATOR.md. |
|
|
31
|
+
| ProfilesController / ProfileController / AccessibilityProfilesController | activeProfile; ProfilePresetId / null | Previews, applies, and reverts eight neutral presets (Motor, Blind, Color Blind, Dyslexia, Low Vision, Cognitive, Seizure, ADHD). Follows deterministic override model where user explicit choices survive reversal. Zero implicit audio/mic. See docs/PROFILES.md. |
|
|
32
|
+
| PresetsController / CustomPresetsController / SettingsImportExportController | customPresets; CustomPreset[] | Saves named user presets, 1-click apply/delete, and versioned JSON backup and transfer. Strict privacy exclusions discard private data, transcripts, and credentials. Saved presets library survives display reset. See docs/PRESETS.md. |
|
|
33
|
+
| ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
|
|
31
34
|
|
|
32
35
|
## Accessible control primitives and UI states
|
|
33
36
|
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Page Headings and Landmarks Navigator
|
|
2
|
+
|
|
3
|
+
This document details the Page Headings and Landmarks Navigator implemented in `accessibility-plugin-react` in accordance with WCAG 2.1 / 2.2 Success Criterion 2.4.1 (Bypass Blocks), 2.4.6 (Headings and Labels), and issue [A11Y-303](https://github.com/prabothcharith/accessibility-react/issues/51).
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Core Principles & Acceptance Criteria
|
|
8
|
+
|
|
9
|
+
1. **True DOM Tree Order**:
|
|
10
|
+
- Discovers actual `h1`–`h6` elements and ARIA headings (`[role="heading"][aria-level]`) in physical document order.
|
|
11
|
+
- Maps top-level landmarks (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`, `<form role="search">`, and ARIA landmark regions) and named anchors (`<a id="...">`, `<a name="...">`).
|
|
12
|
+
- Ignores scoped `<header>` and `<footer>` elements inside `<article>`, `<aside>`, `<main>`, `<nav>`, or `<section>` which are not top-level page landmarks according to the HTML-AAM specification.
|
|
13
|
+
- Strictly excludes internal heading/landmark structures rendered within the accessibility plugin itself (`[data-arap-ui]`).
|
|
14
|
+
2. **Safe Navigation with Temporary TabIndex Cleanup**:
|
|
15
|
+
- Navigating to an element scrolls it smoothly into view (`scrollIntoView({ behavior: 'smooth', block: 'start' })`, or instant if reduced motion is requested).
|
|
16
|
+
- If the target element is naturally focusable (links, buttons, inputs, elements with pre-existing `tabindex`), focus is set directly.
|
|
17
|
+
- If the element is not naturally focusable (standard `h1`-`h6` or generic section containers), a temporary `tabindex="-1"` is assigned to receive keyboard focus. On `blur`, the temporary `tabindex` is removed immediately, restoring original host DOM semantics.
|
|
18
|
+
3. **Truthful Representation on Empty Pages**:
|
|
19
|
+
- If the host document has no headings or no landmarks, the navigator displays an explicit status announcement: `"No headings found on this page."` or `"No landmarks found on this page."`.
|
|
20
|
+
- The plugin never fabricates synthetic headings, phantom landmarks, or placeholder outlines.
|
|
21
|
+
4. **Dynamic SPA / Route Updates Without Observer Loops**:
|
|
22
|
+
- The navigator watches external DOM mutations (`MutationObserver`) while open so client-side route changes update headings and landmarks in real time.
|
|
23
|
+
- Mutations originating inside the plugin UI are strictly ignored, preventing recursive observer loops.
|
|
24
|
+
5. **Keyboard Operability & Rapid Dismissal**:
|
|
25
|
+
- Accessible tabs (`role="tablist"`, `role="tab"`) switchable with `Left` / `Right` arrow keys.
|
|
26
|
+
- Jump buttons support `Enter` and `Space`.
|
|
27
|
+
- Pressing `Escape` closes the explorer dialog and returns keyboard focus to the "Explore" button.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 2. Component Reference
|
|
32
|
+
|
|
33
|
+
### `PageNavigatorController`
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import { PageNavigatorController } from "accessibility-plugin-react";
|
|
37
|
+
|
|
38
|
+
<PageNavigatorController
|
|
39
|
+
label="Page Navigator"
|
|
40
|
+
description="Explore headings and landmarks"
|
|
41
|
+
closeOnNavigate={false}
|
|
42
|
+
/>;
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- **Props**:
|
|
46
|
+
- `label?: string` (default: `"Page Navigator"`): Visible and accessible feature label.
|
|
47
|
+
- `description?: string` (default: `"Explore headings and landmarks"`): Subtitle describing the feature.
|
|
48
|
+
- `closeOnNavigate?: boolean` (default: `false`): If true, automatically closes the navigator explorer once an item is activated.
|
|
49
|
+
- `className?: string`: Custom container classes.
|
|
50
|
+
- **Aliases**: `HeadingsNavigatorController`, `PageStructureController`.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 3. Utility APIs
|
|
55
|
+
|
|
56
|
+
### `scanHeadings(root?: Document | Element): HeadingItem[]`
|
|
57
|
+
|
|
58
|
+
Discovers all visible `h1`-`h6` headings and `role="heading"` elements in DOM tree order, excluding plugin UI elements and hidden elements.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import { scanHeadings } from "accessibility-plugin-react";
|
|
62
|
+
|
|
63
|
+
const headings = scanHeadings();
|
|
64
|
+
// [ { id: "intro", level: 1, text: "Introduction", element: HTMLHeadingElement }, ... ]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### `scanLandmarks(root?: Document | Element): LandmarkItem[]`
|
|
68
|
+
|
|
69
|
+
Discovers visible landmarks (`banner`, `navigation`, `main`, `complementary`, `contentinfo`, `search`, `region`, `form`) and named anchors in DOM tree order.
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { scanLandmarks } from "accessibility-plugin-react";
|
|
73
|
+
|
|
74
|
+
const landmarks = scanLandmarks();
|
|
75
|
+
// [ { id: "site-nav", type: "navigation", label: "Primary Nav", element: HTMLElement }, ... ]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### `navigateToElement(element: HTMLElement, options?: { behavior?: ScrollBehavior, onComplete?: () => void }): void`
|
|
79
|
+
|
|
80
|
+
Safely scrolls to and focuses an element with automatic temporary `tabindex="-1"` cleanup upon blur.
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import { navigateToElement } from "accessibility-plugin-react";
|
|
84
|
+
|
|
85
|
+
navigateToElement(document.querySelector("h2"));
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### `subscribePageStructure(callback: () => void): () => void`
|
|
89
|
+
|
|
90
|
+
Listens to external DOM additions and removals outside `[data-arap-ui]`, invoking the callback with a 100ms debounce.
|