accessibility-plugin-react 2.12.0 → 2.13.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
@@ -1121,3 +1121,57 @@
1121
1121
  flex-direction: column !important;
1122
1122
  align-items: stretch !important;
1123
1123
  }
1124
+
1125
+ /* Accessible Tooltips (A11Y-302) */
1126
+ .arap-accessible-tooltip {
1127
+ position: fixed !important;
1128
+ z-index: 2147483646 !important;
1129
+ max-width: 320px !important;
1130
+ min-width: 48px !important;
1131
+ box-sizing: border-box !important;
1132
+ padding: 6px 12px !important;
1133
+ background: #0f172a !important;
1134
+ color: #ffffff !important;
1135
+ font-family:
1136
+ -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
1137
+ Arial, sans-serif !important;
1138
+ font-size: 13px !important;
1139
+ line-height: 1.4 !important;
1140
+ font-weight: 500 !important;
1141
+ border-radius: 6px !important;
1142
+ box-shadow:
1143
+ 0 4px 14px rgba(0, 0, 0, 0.25),
1144
+ 0 0 0 1px rgba(255, 255, 255, 0.15) !important;
1145
+ pointer-events: auto !important;
1146
+ word-break: break-word !important;
1147
+ white-space: normal !important;
1148
+ opacity: 0 !important;
1149
+ visibility: hidden !important;
1150
+ transition:
1151
+ opacity 120ms ease,
1152
+ transform 120ms ease !important;
1153
+ transform: translateY(2px) !important;
1154
+ }
1155
+
1156
+ .arap-accessible-tooltip[data-visible="true"] {
1157
+ opacity: 1 !important;
1158
+ visibility: visible !important;
1159
+ transform: translateY(0) !important;
1160
+ }
1161
+
1162
+ .arap-accessible-tooltip[data-placement="top"] {
1163
+ transform: translateY(-2px) !important;
1164
+ }
1165
+
1166
+ .arap-accessible-tooltip[data-placement="top"][data-visible="true"] {
1167
+ transform: translateY(0) !important;
1168
+ }
1169
+
1170
+ @media (forced-colors: active) {
1171
+ .arap-accessible-tooltip {
1172
+ background: Canvas !important;
1173
+ color: CanvasText !important;
1174
+ border: 2px solid Highlight !important;
1175
+ box-shadow: none !important;
1176
+ }
1177
+ }
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`, `SkipToMainLinkProps`, `HideImagesControllerProps`, `BigCursorControllerProps`, `ReadingMaskControllerProps`, `ReadingGuideControllerProps`, `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`, `HideImagesControllerProps`, `BigCursorControllerProps`, `ReadingMaskControllerProps`, `ReadingGuideControllerProps`, `TooltipsControllerProps`, `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`, `LinkHighlightController`, `HighlightFocusController`, `FocusHighlightController`, `ReduceMotionController`, `HideImagesController`, `HideDecorativeImagesController`, `BigCursorController`, `ReadingMaskController`, `ReadingGuideController`, `SkipToMainLink`.
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`.
54
54
 
55
- Exported typography, contrast, reading aids, 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`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`.
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`.
56
56
 
57
57
  Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
58
58
 
@@ -94,7 +94,7 @@ completed. Closing a child issue does not replace the milestone exit review.
94
94
  ### M3 — Reading support, profiles and localization
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
- - [ ] [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.
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
98
  - [ ] [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
99
  - [ ] [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
100
  - [ ] [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.
package/docs/FEATURES.md CHANGED
@@ -26,6 +26,7 @@ All features are opt-in via controllers, use native buttons, support Enter/Space
26
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
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
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. |
29
30
  | ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
30
31
 
31
32
  ## Accessible control primitives and UI states
@@ -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.12.0",
3
+ "version": "2.13.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",