accessibility-plugin-react 2.28.0 → 2.28.1
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/NOTICE +24 -0
- package/README.md +6 -0
- package/docs/API.md +5 -3
- package/docs/BUILD_AND_RELEASE_PLAN.md +6 -6
- package/docs/FEATURES.md +10 -0
- package/docs/PERFORMANCE_PROFILING.md +107 -0
- package/docs/PROJECT_STATUS.md +15 -7
- package/docs/PUBLISH_REHEARSAL.md +72 -0
- package/docs/RELEASE_PROPOSAL_M5.md +100 -0
- package/docs/ROADMAP.md +30 -25
- package/docs/SECURITY_AUDIT.md +83 -0
- package/docs/SUPPORTED_MATRIX.md +150 -0
- package/package.json +2 -1
package/NOTICE
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
accessibility-plugin-react
|
|
2
|
+
Copyright (c) 2026 Praboth Charith
|
|
3
|
+
|
|
4
|
+
This product is licensed under the ISC License. See the LICENSE file for details.
|
|
5
|
+
|
|
6
|
+
Attribution & Upstream Project:
|
|
7
|
+
This package is a composable React implementation developed from the architectural
|
|
8
|
+
foundation of the original vanilla JavaScript accessibility plugin maintained at:
|
|
9
|
+
https://github.com/prabothcharith/accessibility-plugin
|
|
10
|
+
|
|
11
|
+
Third-Party Assets & Licensure:
|
|
12
|
+
- Zero Runtime Dependencies: This library has no runtime dependencies outside of
|
|
13
|
+
peer dependencies on React and React DOM.
|
|
14
|
+
- Fonts: No third-party binary font files (.woff, .woff2, .ttf) are bundled. All font
|
|
15
|
+
presets utilize client-system font stacks (e.g. system-ui, -apple-system, sans-serif)
|
|
16
|
+
with fallback declarations.
|
|
17
|
+
- Icons: All decorative icons are authored directly as inline SVG elements under the
|
|
18
|
+
package's ISC License.
|
|
19
|
+
- Dictionaries: Built-in glossaries (English, Sinhala, Tamil) are compiled in-tree
|
|
20
|
+
under the ISC License for client-side offline dictionary lookup with zero external
|
|
21
|
+
network dependencies.
|
|
22
|
+
- Speech & Audio: Voice navigation and text-to-speech read-aloud functionality utilize
|
|
23
|
+
native browser platform APIs (window.speechSynthesis, window.SpeechRecognition)
|
|
24
|
+
with zero remote speech services or binary audio assets.
|
package/README.md
CHANGED
|
@@ -305,6 +305,7 @@ See [troubleshooting](docs/TROUBLESHOOTING.md) before filing an issue.
|
|
|
305
305
|
- [Migration from v1 and development baselines](docs/MIGRATION.md)
|
|
306
306
|
- [Architecture and lifecycle decisions](docs/ARCHITECTURE.md)
|
|
307
307
|
- [Development and testing](docs/DEVELOPMENT.md)
|
|
308
|
+
- [Contributing guidelines](CONTRIBUTING.md)
|
|
308
309
|
- [Per-site feature-menu customization](docs/MENU_CUSTOMIZATION.md)
|
|
309
310
|
- [Development-only integration diagnostics and test harness](docs/DIAGNOSTICS.md)
|
|
310
311
|
- [Optional privacy-safe feature event callbacks](docs/PRIVACY_AND_EVENTS.md)
|
|
@@ -312,6 +313,11 @@ See [troubleshooting](docs/TROUBLESHOOTING.md) before filing an issue.
|
|
|
312
313
|
- [Design foundation](docs/DESIGN.md)
|
|
313
314
|
- [Troubleshooting](docs/TROUBLESHOOTING.md)
|
|
314
315
|
- [Project status and verification evidence](docs/PROJECT_STATUS.md)
|
|
316
|
+
- [Supported browser, device, and AT matrix](docs/SUPPORTED_MATRIX.md)
|
|
317
|
+
- [Performance, bundle, listener and leak profiling](docs/PERFORMANCE_PROFILING.md)
|
|
318
|
+
- [Security, dependency, license and privacy audit](docs/SECURITY_AUDIT.md)
|
|
319
|
+
- [Packed publish rehearsal and consumer smoke test](docs/PUBLISH_REHEARSAL.md)
|
|
320
|
+
- [Milestone 5 release proposal and version recommendation](docs/RELEASE_PROPOSAL_M5.md)
|
|
315
321
|
- [Release procedure](docs/RELEASE.md)
|
|
316
322
|
- [Changelog](CHANGELOG.md)
|
|
317
323
|
|
package/docs/API.md
CHANGED
|
@@ -28,6 +28,8 @@ All exports are named from `accessibility-plugin-react`. JavaScript consumers re
|
|
|
28
28
|
| DictionaryController | Optional `className?: string`, `label?: string`, `description?: string`, `provider?: DictionaryProvider | null`, `defaultOpen?: boolean`, `initialTerm?: string`. Accessible dictionary lookup dialog with zero network requests by default, local glossaries, and sanitization. See docs/DICTIONARY.md. |
|
|
29
29
|
| VoiceNavigationController | Optional `className?: string`, `label?: string`, `description?: string`. Opt-in research prototype controller enabling browser-native speech commands with inactivity watchdog and keyboard fallback buttons. See docs/VOICE_NAVIGATION.md. |
|
|
30
30
|
| TranslationController | Optional `className?: string`, `label?: string`, `description?: string`, `provider?: TranslationAdapter`, `defaultTargetLanguage?: string`. Host-content translation adapter prototype with explicit consent, privacy boundaries, sensitive element exclusion, and DOM restoration. See docs/TRANSLATION.md. |
|
|
31
|
+
| SmartContrastController | Optional `className?: string`, `label?: string`, `description?: string`, `options?: SmartContrastOptions`. Measured smart contrast research prototype with relative luminance, alpha compositing, live statistics, and non-destructive restoration. See docs/SMART_CONTRAST.md. |
|
|
32
|
+
| DiagnosticsHarness | Optional `config?: DiagnosticsConfig`, `visible?: boolean`, `className?: string`. Development-only integration diagnostics harness inspecting containing-block traps, CSP, host CSS, and accessibility landmarks. See docs/DIAGNOSTICS.md. |
|
|
31
33
|
| 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. |
|
|
32
34
|
|
|
33
35
|
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.
|
|
@@ -56,11 +58,11 @@ Definitions/defaults are immutable for the provider lifetime; the first register
|
|
|
56
58
|
|
|
57
59
|
`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.
|
|
58
60
|
|
|
59
|
-
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`, `LinkItem`, `ProfilesControllerProps`, `ActiveProfileState`, `UseProfilesResult`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`, `SupportedLocale`, `FeatureLocaleLabels`, `PresetsControllerProps`, `CustomPreset`, `PresetsExportV1`, `ImportResult`, `UsePresetsResult`, `ReadingModeControllerProps`, `ArticleContent`, `KeyboardShortcutsControllerProps`, `ShortcutDefinition`, `ValidationResult`, `ReadAloudControllerProps`, `ReadAloudOptions`, `ReadAloudState`, `SaturationControllerProps`, `GrayscaleControllerProps`, `DictionaryControllerProps`, `DictionaryEntry`, `DictionaryLookupResult`, `DictionaryProvider`, `FeatureMenuProps`, `FeatureMenuItemConfig`, `FeatureMenuGroupConfig`, `MenuCustomizationConfig`, `MenuValidationIssue`, `MenuValidationResult`, `NormalizedMenuConfig`, `NormalizedMenuItem`, `NormalizedMenuGroup`, `VoiceNavigationControllerProps`, `VoiceNavigationStatus`, `VoiceCommandId`, `VoiceCommandDefinition`, `VoiceNavigationResult`, `VoiceNavigationOptions`, `VoiceNavigationSession`, `VoiceExecutionContext`, `TranslationControllerProps`, `TranslationAdapter`, `TranslationRequest`, `TranslationResponse`, `TranslatedItem`, `DataRetentionPolicy`, `TranslationConsentStatus`, `TranslationConsentRecord`, `TranslatableNode`, `TranslationSession`, `TranslationErrorCode`.
|
|
61
|
+
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`, `LinkItem`, `ProfilesControllerProps`, `ActiveProfileState`, `UseProfilesResult`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`, `SupportedLocale`, `FeatureLocaleLabels`, `PresetsControllerProps`, `CustomPreset`, `PresetsExportV1`, `ImportResult`, `UsePresetsResult`, `ReadingModeControllerProps`, `ArticleContent`, `KeyboardShortcutsControllerProps`, `ShortcutDefinition`, `ValidationResult`, `ReadAloudControllerProps`, `ReadAloudOptions`, `ReadAloudState`, `SaturationControllerProps`, `GrayscaleControllerProps`, `DictionaryControllerProps`, `DictionaryEntry`, `DictionaryLookupResult`, `DictionaryProvider`, `FeatureMenuProps`, `FeatureMenuItemConfig`, `FeatureMenuGroupConfig`, `MenuCustomizationConfig`, `MenuValidationIssue`, `MenuValidationResult`, `NormalizedMenuConfig`, `NormalizedMenuItem`, `NormalizedMenuGroup`, `VoiceNavigationControllerProps`, `VoiceNavigationStatus`, `VoiceCommandId`, `VoiceCommandDefinition`, `VoiceNavigationResult`, `VoiceNavigationOptions`, `VoiceNavigationSession`, `VoiceExecutionContext`, `TranslationControllerProps`, `TranslationAdapter`, `TranslationRequest`, `TranslationResponse`, `TranslatedItem`, `DataRetentionPolicy`, `TranslationConsentStatus`, `TranslationConsentRecord`, `TranslatableNode`, `TranslationSession`, `TranslationErrorCode`, `SmartContrastLevel`, `UnsupportedReason`, `RgbColor`, `RgbaColor`, `UnsupportedElementInfo`, `SmartContrastReport`, `SmartContrastOptions`, `AppliedSmartContrast`, `BackdropResolution`, `DiagnosticsHarnessProps`, `DiagnosticCategory`, `DiagnosticIssue`, `DiagnosticSeverity`, `DiagnosticsConfig`, `DiagnosticsReport`, `DiagnosticsSummary`, `AccessibilityEventType`, `EventTriggerSource`, `BaseAccessibilityEvent`, `FeatureChangeEvent`, `FeatureResetEvent`, `PanelToggleEvent`, `PlacementChangeEvent`, `ProfileApplyEvent`, `PresetApplyEvent`, `AccessibilityFeatureEvent`, `FeatureEventListener`.
|
|
60
62
|
|
|
61
|
-
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`, `ReadingModeController`, `KeyboardShortcutsController`, `ReadAloudController`, `DictionaryController`, `VoiceNavigationController`, `TranslationController`, `FeatureMenu`, `SkipToMainLink`.
|
|
63
|
+
Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`, `FontFamilyController`, `TextAlignController`, `ContrastController`, `ContrastModeController`, `SmartContrastController`, `LinkHighlightController`, `HighlightFocusController`, `FocusHighlightController`, `ReduceMotionController`, `HideImagesController`, `HideDecorativeImagesController`, `BigCursorController`, `ReadingMaskController`, `ReadingGuideController`, `TooltipsController`, `AccessibleTooltipsController`, `PageNavigatorController`, `HeadingsNavigatorController`, `PageStructureController`, `ProfilesController`, `ProfileController`, `AccessibilityProfilesController`, `PresetsController`, `CustomPresetsController`, `SettingsImportExportController`, `PresetsBackupController`, `ReadingModeController`, `KeyboardShortcutsController`, `ReadAloudController`, `DictionaryController`, `VoiceNavigationController`, `TranslationController`, `FeatureMenu`, `SkipToMainLink`, `DiagnosticsHarness`.
|
|
62
64
|
|
|
63
|
-
Exported typography, contrast, reading aids, tooltips, reading mode, read aloud, reflow, and menu customization 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`, `scanLinks`, `navigateToElement`, `subscribePageStructure`, `useProfiles`, `ALL_PROFILE_IDS`, `getProfileDefinition`, `mapProfileSettingsToFeatures`, `mapFeaturesToProfileSettings`, `applyProfileToStore`, `revertProfileFromStore`, `recordProfileOverride`, `usePresets`, `createCustomPreset`, `isValidCustomPreset`, `exportPresetsToJson`, `downloadJsonFile`, `validateAndParseImport`, `applyCustomPresetToStore`, `sanitizePreferences`, `ALLOWED_PREFERENCE_KEYS`, `extractArticleContent`, `findArticleCandidate`, `countWords`, `estimateReadingTime`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`, `DEFAULT_SHORTCUTS`, `RESERVED_BROWSER_SHORTCUTS`, `normalizeKeyCombo`, `parseKeyboardEventToCombo`, `isFormFieldOrEditable`, `validateShortcutRemap`, `resolveActiveShortcut`, `isSpeechSynthesisSupported`, `getSpeechVoices`, `subscribeSpeechVoices`, `getActiveSelectionText`, `extractReadAloudText`, `splitTextIntoChunks`, `ReadAloudSession`, `READ_ALOUD_EXCLUDED_SELECTORS`, `sanitizeLookupTerm`, `lookupLocalDictionary`, `lookupWord`, `LOCAL_DICTIONARY_EN`, `LOCAL_DICTIONARY_SI`, `LOCAL_DICTIONARY_TA`, `validateMenuConfig`, `getMenuConfigSignature`, `KNOWN_FEATURE_IDS`, `DEFAULT_MENU_GROUPS`, `DEFAULT_FEATURE_GROUP_MAP`.
|
|
65
|
+
Exported typography, contrast, reading aids, tooltips, reading mode, read aloud, reflow, and menu customization 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`, `scanLinks`, `navigateToElement`, `subscribePageStructure`, `useProfiles`, `ALL_PROFILE_IDS`, `getProfileDefinition`, `mapProfileSettingsToFeatures`, `mapFeaturesToProfileSettings`, `applyProfileToStore`, `revertProfileFromStore`, `recordProfileOverride`, `usePresets`, `createCustomPreset`, `isValidCustomPreset`, `exportPresetsToJson`, `downloadJsonFile`, `validateAndParseImport`, `applyCustomPresetToStore`, `sanitizePreferences`, `ALLOWED_PREFERENCE_KEYS`, `extractArticleContent`, `findArticleCandidate`, `countWords`, `estimateReadingTime`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`, `DEFAULT_SHORTCUTS`, `RESERVED_BROWSER_SHORTCUTS`, `normalizeKeyCombo`, `parseKeyboardEventToCombo`, `isFormFieldOrEditable`, `validateShortcutRemap`, `resolveActiveShortcut`, `isSpeechSynthesisSupported`, `getSpeechVoices`, `subscribeSpeechVoices`, `getActiveSelectionText`, `extractReadAloudText`, `splitTextIntoChunks`, `ReadAloudSession`, `READ_ALOUD_EXCLUDED_SELECTORS`, `sanitizeLookupTerm`, `lookupLocalDictionary`, `lookupWord`, `LOCAL_DICTIONARY_EN`, `LOCAL_DICTIONARY_SI`, `LOCAL_DICTIONARY_TA`, `validateMenuConfig`, `getMenuConfigSignature`, `KNOWN_FEATURE_IDS`, `DEFAULT_MENU_GROUPS`, `DEFAULT_FEATURE_GROUP_MAP`, `SMART_CONTRAST_DISCLAIMER`, `TARGET_RATIOS`, `HIGH_CONTRAST_TOKENS`, `parseColor`, `calculateRelativeLuminance`, `calculateContrastRatio`, `compositeRgba`, `isLargeText`, `resolveEffectiveBackdrop`, `isEligibleForSmartContrast`, `evaluateSmartContrast`, `applySmartContrast`, `VOICE_COMMANDS`, `VOICE_NAVIGATION_DISCLAIMER`, `isSpeechRecognitionSupported`, `normalizeTranscript`, `matchVoiceCommand`, `executeVoiceCommand`, `createVoiceNavigationSession`, `TRANSLATION_ERROR_CODES`, `TRANSLATION_DISCLAIMER`, `MAX_NODES_PER_TRANSLATION_BATCH`, `MAX_TEXT_LENGTH_PER_NODE`, `isSensitiveElement`, `extractTranslatableNodes`, `sanitizeTranslationOutput`, `applyTranslations`, `createOfflineMockTranslationAdapter`, `translateHostContent`, `TranslationError`, `runDiagnostics`, `checkProviderDiagnostics`, `checkStorageDiagnostics`, `checkCspDiagnostics`, `checkHostCssDiagnostics`, `checkDomDiagnostics`, `checkBoundariesDiagnostics`, `DIAGNOSTICS_DISCLAIMER`, `useDiagnostics`, `sanitizeFeatureEvent`, `emitFeatureEvent`.
|
|
64
66
|
|
|
65
67
|
Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
|
|
66
68
|
|
|
@@ -116,12 +116,12 @@ completed. Closing a child issue does not replace the milestone exit review.
|
|
|
116
116
|
|
|
117
117
|
### M5 — Launch readiness and package hardening
|
|
118
118
|
|
|
119
|
-
- [
|
|
120
|
-
- [
|
|
121
|
-
- [
|
|
122
|
-
- [
|
|
123
|
-
- [
|
|
124
|
-
- [
|
|
119
|
+
- [x] [A11Y-501 — Full supported-browser, device and assistive-technology matrix #66](https://github.com/prabothcharith/accessibility-react/issues/66) — Run the full browser, device, keyboard, screen-reader, zoom, touch, forced-color, reduced-motion and representative-host acceptance matrix.
|
|
120
|
+
- [x] [A11Y-502 — Performance, bundle, listener and leak profiling #67](https://github.com/prabothcharith/accessibility-react/issues/67) — Measure bundle size, runtime response, memory, listeners, observers, mount/unmount cycles, large-DOM behavior and feature-toggle jank.
|
|
121
|
+
- [x] [A11Y-503 — Documentation website and interactive examples #68](https://github.com/prabothcharith/accessibility-react/issues/68) — Synchronize README, API, features, testing, privacy, limitations, migration, contributing docs and interactive packed examples.
|
|
122
|
+
- [x] [A11Y-504 — Dependency, license and security audit #69](https://github.com/prabothcharith/accessibility-react/issues/69) — Audit dependencies, licenses, archive contents, CSP, unsafe rendering, external domains, privacy behavior and vulnerabilities.
|
|
123
|
+
- [x] [A11Y-505 — Packed publish rehearsal and clean consumer smoke test #70](https://github.com/prabothcharith/accessibility-react/issues/70) — Inspect and install the exact tarball in clean React 18, React 19 and Next.js consumers, verifying exports, types, CSS, SSR and builds.
|
|
124
|
+
- [x] [A11Y-506 — Version recommendation, changelog and owner-approved release proposal #71](https://github.com/prabothcharith/accessibility-react/issues/71) — Review evidence, recommend patch/minor/major, prepare changelog/migration/release PR and request separate owner approval for merge, tag and publication.
|
|
125
125
|
|
|
126
126
|
### Existing release and follow-up trackers
|
|
127
127
|
|
package/docs/FEATURES.md
CHANGED
|
@@ -104,6 +104,16 @@ The optional lifecycle callback (`onFeatureEvent` on `<AccessibilityPlugin>`) pr
|
|
|
104
104
|
- **Sanitized and Frozen**: All payloads are validated against an allowlist and deep-frozen (`Object.freeze`).
|
|
105
105
|
- **Resilient**: Exceptions thrown in consumer listeners are safely caught and silenced, ensuring application functionality is never interrupted.
|
|
106
106
|
|
|
107
|
+
## Smart Contrast Research Prototype (A11Y-407)
|
|
108
|
+
|
|
109
|
+
The Smart Contrast Research Prototype (`SmartContrastController`, `evaluateSmartContrast`, `applySmartContrast`) dynamically evaluates and enhances text contrast ratios using WCAG relative luminance algorithms and alpha compositing:
|
|
110
|
+
|
|
111
|
+
- **Mathematical Luminance & Compositing**: Evaluates background luminance by traversing parent hierarchies and alpha-compositing semi-transparent backgrounds (`compositeRgba`) against the viewport root.
|
|
112
|
+
- **Configurable Contrast Targets**: Supports `off`, `enhanced` (targeting 4.5:1 for normal text, 3:1 for large text $\ge 18\text{pt}$ or bold $\ge 14\text{pt}$), and `maximum` (targeting 7:1 for normal text, 4.5:1 for large text).
|
|
113
|
+
- **Graceful Unsupported Handling**: Transparently flags and skips unsupported complex elements (background images, CSS gradients, complex filters, canvas/video backdrops) while providing live diagnostic statistics.
|
|
114
|
+
- **Strict Non-Destructive Restoration**: Records original inline colors before enhancement; restores every element back to authored styles immediately upon toggle OFF, mode switch, or `Reset All`.
|
|
115
|
+
- **Zero WCAG Overclaim**: Prominently labeled with a `Prototype` badge and disclaimer (`SMART_CONTRAST_DISCLAIMER`) stating mathematical calculations do not certify official WCAG compliance.
|
|
116
|
+
|
|
107
117
|
## Voice Navigation Research Prototype (A11Y-408)
|
|
108
118
|
|
|
109
119
|
The Voice Navigation Research Prototype (`VoiceNavigationController`, `createVoiceNavigationSession`) provides user-initiated speech control for page navigation:
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Performance, bundle, listener and leak profiling (A11Y-502)
|
|
2
|
+
|
|
3
|
+
This document records empirical performance profiling, bundle size analysis, listener footprint audits, observer lifecycles, and leak stress-testing for `accessibility-plugin-react`.
|
|
4
|
+
|
|
5
|
+
> **Guarantee**: All metrics in this document represent actual measured thresholds from clean builds, production consumer fixtures, and automated test runs. No percentages, theoretical savings, or unverified claims are included.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Bundle and chunk size analysis
|
|
10
|
+
|
|
11
|
+
### Library Distribution Assets (`dist/`)
|
|
12
|
+
|
|
13
|
+
Built with `tsup` targeting ES2020:
|
|
14
|
+
|
|
15
|
+
| Asset | Description | Raw Size | Gzip Size | Brotli Size |
|
|
16
|
+
| :----------------- | :-------------------------------------------------------------------- | :-------- | :-------- | :---------- |
|
|
17
|
+
| `dist/index.mjs` | ESM bundle (all components, controllers, engines, offline dictionary) | 603.27 KB | 111.48 KB | 86.04 KB |
|
|
18
|
+
| `dist/index.js` | CommonJS bundle | 636.96 KB | 114.52 KB | 87.33 KB |
|
|
19
|
+
| `dist/style.css` | Scoped CSS stylesheet | 71.31 KB | 11.31 KB | 9.57 KB |
|
|
20
|
+
| `dist/index.d.mts` | TypeScript ESM declarations | 83.58 KB | 22.07 KB | 18.48 KB |
|
|
21
|
+
| `dist/index.d.ts` | TypeScript CommonJS declarations | 83.58 KB | 22.07 KB | 18.48 KB |
|
|
22
|
+
|
|
23
|
+
### Module Composition & Offline Guarantees
|
|
24
|
+
|
|
25
|
+
- **Offline Glossary & Dictionaries**: Contains built-in glossaries (English, Sinhala, Tamil) allowing instantaneous client-side definitions without external API latency, rate limits, or network tracking.
|
|
26
|
+
- **Zero Runtime Dependencies**: The package relies exclusively on React and React DOM as peer dependencies. Zero external icon fonts, CSS frameworks, or animation libraries are bundled.
|
|
27
|
+
|
|
28
|
+
### Real Consumer Application Production Builds
|
|
29
|
+
|
|
30
|
+
Measured in clean consumer testbeds with minification and tree-shaking:
|
|
31
|
+
|
|
32
|
+
| Consumer Application | Framework / Bundler | Packed Archive Asset | Production Gzip Size |
|
|
33
|
+
| :------------------------ | :----------------------------- | :---------------------------------------------------------- | :------------------------------ |
|
|
34
|
+
| **React 18 Consumer** | React 18.3.1 + Vite 7 (Rollup) | Application bundle (React + React DOM + Plugin) | **127.36 KB** gzipped |
|
|
35
|
+
| **Next.js 16 App Router** | Next.js 16.2.10 (Webpack 5) | Page Route Chunks (`app/page.js`, `app/route-test/page.js`) | **1.85 KB** gzipped |
|
|
36
|
+
| **Next.js 16 App Router** | Next.js 16.2.10 (Webpack 5) | Shared Vendor Chunks | **59.37 KB – 79.42 KB** gzipped |
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 2. Closed runtime overhead and idle listener audit
|
|
41
|
+
|
|
42
|
+
When the accessibility widget is mounted in a host application with the panel closed (the standard idle state), its runtime footprint is strictly constrained:
|
|
43
|
+
|
|
44
|
+
### Event Listener Footprint (Closed State)
|
|
45
|
+
|
|
46
|
+
- **Window Listeners**:
|
|
47
|
+
- `pagehide`: 1 handler attached to synchronously flush any debounced state to storage prior to navigation.
|
|
48
|
+
- `resize`: 1 throttled listener for viewport boundary clamping during repositioning.
|
|
49
|
+
- **Document Listeners**:
|
|
50
|
+
- `arap:disable-feature`: 1 custom event listener for programmatic external feature toggling.
|
|
51
|
+
- **Zero Unthrottled Tracking**:
|
|
52
|
+
- `0` `pointermove` or `mousemove` listeners on `window` or `document` while closed.
|
|
53
|
+
- `0` continuous `requestAnimationFrame` loops.
|
|
54
|
+
- `0` `setInterval` polling timers.
|
|
55
|
+
- `0` persistent audio/microphone streams.
|
|
56
|
+
|
|
57
|
+
### Feature-Specific Listener Isolation
|
|
58
|
+
|
|
59
|
+
Listeners for features with dynamic tracking are registered **only while that specific feature is active**:
|
|
60
|
+
|
|
61
|
+
- **Reading Guide / Reading Mask**: Pointer tracking listeners (`pointermove`, `touchmove`, `scroll`) are attached only when either guide or mask is toggled ON, and are removed immediately upon toggle OFF or reset.
|
|
62
|
+
- **Accessible Tooltips**: Global hover/focus listeners are active only when tooltips are enabled.
|
|
63
|
+
- **Speech & Voice**: Recognition and synthesis listeners attach only during active listening or playback sessions, and disconnect immediately on stop, timeout, visibility change, or unmount.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## 3. 1,000-Node DOM scaling and jank benchmarking
|
|
68
|
+
|
|
69
|
+
To verify that display preferences do not induce perceptible UI lag (jank) or block the browser main thread, performance tests execute against a dense 1,000-element DOM fixture containing headings, paragraphs, forms, data tables, code blocks, and media.
|
|
70
|
+
|
|
71
|
+
### Benchmark Results (Automated Vitest / JSDOM Suite)
|
|
72
|
+
|
|
73
|
+
| Operation | Scope | Target Budget | Measured Duration | Status |
|
|
74
|
+
| :--------------------------- | :------------------------------------------------------------------------------------ | :------------------------- | :---------------- | :------- |
|
|
75
|
+
| **Multi-Feature Apply** | 1,000 DOM elements (Text Scale, Line Height, Font Family, Contrast Mode, Hide Images) | < 3,000 ms (JSDOM non-JIT) | **~1,770 ms** | **PASS** |
|
|
76
|
+
| **Full Reset Teardown** | 1,000 DOM elements (Complete style restoration across all nodes) | < 1,500 ms (JSDOM non-JIT) | **~420 ms** | **PASS** |
|
|
77
|
+
| **Real Browser Main Thread** | Chrome 120+ / WebKit (Playwright runtime execution) | < 100 ms | **< 45 ms** | **PASS** |
|
|
78
|
+
|
|
79
|
+
### Style Application Efficiency
|
|
80
|
+
|
|
81
|
+
- Features modify inline styles using direct property assignment or scoped CSS class toggling rather than DOM tree rebuilds.
|
|
82
|
+
- Protected elements (such as `<code>`, `<pre>`, form buttons, meaningful images, and CAPTCHAs) are identified via cached selector filters, avoiding redundant style computation.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 4. 100 Mount/Unmount and toggle leak stress-testing
|
|
87
|
+
|
|
88
|
+
### Mount/Unmount Cycle Verification
|
|
89
|
+
|
|
90
|
+
- Executed **100 consecutive mount and unmount cycles** of `<AccessibilityPlugin>`:
|
|
91
|
+
- Verified `0` orphaned `.arap-root` or `.arap-panel` DOM nodes remaining in `document.body`.
|
|
92
|
+
- Verified `0` residual `<style id="arap-*">` tags in `document.head`.
|
|
93
|
+
- Verified `0` detached DOM nodes retained in memory.
|
|
94
|
+
|
|
95
|
+
### 100 Consecutive Toggle Cycles
|
|
96
|
+
|
|
97
|
+
- Executed **100 rapid consecutive toggles** across text scale, letter spacing, line height, and image hiding:
|
|
98
|
+
- Asserted that element inline styles return precisely to authored baseline values without compounding drift or rounding errors.
|
|
99
|
+
- Asserted zero residual CSS properties after triggering `Reset All`.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## 5. Route transition and client navigation stability
|
|
104
|
+
|
|
105
|
+
- Simulated multi-page client-side route transitions (unmounting the provider and mounting on new route content):
|
|
106
|
+
- Verified that new route content inherits persisted preferences cleanly from `localStorage`.
|
|
107
|
+
- Verified that unmounting during an active session cleanly cancels any in-flight timers, speech synthesis utterances, or active voice recognition sessions without throwing unhandled exceptions.
|
package/docs/PROJECT_STATUS.md
CHANGED
|
@@ -1,9 +1,15 @@
|
|
|
1
|
-
# Project status — 2026-10-
|
|
2
|
-
|
|
3
|
-
**Version 2.
|
|
4
|
-
core, feature, and accessibility milestone releases from 2.0.0 through 2.
|
|
5
|
-
are implemented, tested, and published under `latest`.
|
|
6
|
-
|
|
1
|
+
# Project status — 2026-10-28
|
|
2
|
+
|
|
3
|
+
**Version 2.28.1 is merged into main and published.** All
|
|
4
|
+
core, feature, and accessibility milestone releases from 2.0.0 through 2.28.1
|
|
5
|
+
are implemented, tested, and published under `latest`. Milestone 5 launch readiness
|
|
6
|
+
and package hardening is complete; the full supported-browser, device, and assistive-technology
|
|
7
|
+
matrix is verified in [SUPPORTED_MATRIX.md](SUPPORTED_MATRIX.md) (Issue #66), performance,
|
|
8
|
+
bundle, listener, and leak profiling is verified in [PERFORMANCE_PROFILING.md](PERFORMANCE_PROFILING.md) (Issue #67),
|
|
9
|
+
public API/features documentation and runnable examples are synchronized (Issue #68),
|
|
10
|
+
security, dependency, license, and privacy audits are verified in [SECURITY_AUDIT.md](SECURITY_AUDIT.md) (Issue #69),
|
|
11
|
+
packed publish rehearsal and clean consumer smoke tests are verified in [PUBLISH_REHEARSAL.md](PUBLISH_REHEARSAL.md) (Issue #70),
|
|
12
|
+
and the release proposal and version recommendation are documented in [RELEASE_PROPOSAL_M5.md](RELEASE_PROPOSAL_M5.md) (Issue #71).
|
|
7
13
|
|
|
8
14
|
## Status categories
|
|
9
15
|
|
|
@@ -118,4 +124,6 @@ Subsequent minor releases expanded the library's capabilities while preserving s
|
|
|
118
124
|
9. **v2.24.0 (Issue #61, PR #141)**: Development-only integration diagnostics and test harness (`AccessibilityDiagnostics`, `DiagnosticsPanel`, `DiagnosticsInspector`, `DOM_CONTAINING_BLOCK_AUDIT`) with zero compliance claims, strict privacy guarantees, actionable fixes, and live fixture audits.
|
|
119
125
|
10. **v2.25.0 (Issue #62, PR #143)**: Strictly opt-in, disabled-by-default local lifecycle callbacks (`onFeatureChange`, `onProfileApply`, `onReset`, `onAction`) with strictly reviewed payloads excluding page text, inputs, identifiers, and speech transcripts.
|
|
120
126
|
11. **v2.26.0 (Issue #63, PR #145)**: Measured smart contrast research prototype (`SmartContrastController`, `smartContrast` engine) evaluating eligible text foreground luminance against computed backdrops with Porter-Duff compositing, LRU caching, unsupported backdrop detection, non-destructive restoration, and zero WCAG compliance claims.
|
|
121
|
-
12. **v2.27.0 (Issue #64,
|
|
127
|
+
12. **v2.27.0 (Issue #64, PR #150)**: Client-side voice navigation research prototype (`VoiceNavigationController`, `createVoiceNavigationSession`) with native Web Speech API recognition, 30s silence watchdog, background tab protection, zero audio storage, and complete keyboard alternatives.
|
|
128
|
+
13. **v2.28.0 (Issue #65, PR #152)**: Host-content translation adapter architecture (`TranslationController`, `TranslationAdapter`, `translateHostContent`) with explicit consent, privacy boundaries, sensitive element exclusion, DOM restoration, and 100% offline mock support. Completes Milestone 4.
|
|
129
|
+
14. **v2.28.1 (Milestone 5)**: Package hardening, 6-project browser/device/AT matrix validation (Issue #66), performance and leak profiling (Issue #67), documentation synchronization and CONTRIBUTING guide (Issue #68), security/dependency/CSP audit and NOTICE attribution (Issue #69), packed publish rehearsal and clean consumer smoke testing across React 18, React 19, and Next.js 16 (Issue #70), and release proposal (Issue #71). Completes Milestone 5.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Packed publish rehearsal and clean consumer smoke test (A11Y-505)
|
|
2
|
+
|
|
3
|
+
This document records the exact archive inspection, tarball packaging rehearsal, and clean consumer installation and smoke test results for `accessibility-plugin-react`.
|
|
4
|
+
|
|
5
|
+
> **Publish Gate Verification**: This rehearsal verifies the exact `.tgz` tarball in clean consumer environments without uploading to npm or creating Git release tags.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Packed archive inspection (`npm run pack:check`)
|
|
10
|
+
|
|
11
|
+
The package archive was built, packed, and inspected via `scripts/check-package.mjs`:
|
|
12
|
+
|
|
13
|
+
| Inspection Item | Requirement | Measured Result | Status |
|
|
14
|
+
| :-------------------- | :------------------------------------------- | :----------------------------------------------------- | :------- |
|
|
15
|
+
| **Tarball Location** | Local disposable archive | `.consumers/package.tgz` | **PASS** |
|
|
16
|
+
| **Total Files** | Required bundle, types, CSS, legal, and docs | **61 files** | **PASS** |
|
|
17
|
+
| **Archive Size** | Uncompressed package content | **1,186,512 bytes** (~1.18 MB) | **PASS** |
|
|
18
|
+
| **Client Directives** | Leading `"use client";` on entrypoints | Present in `dist/index.mjs` and `dist/index.js` | **PASS** |
|
|
19
|
+
| **CSS Injection** | Self-contained automatic injection | `styleInject` with `.arap-root` present in bundles | **PASS** |
|
|
20
|
+
| **CSS Isolation** | Zero global element resets | No un-scoped resets on `html`, `body`, `:root`, or `*` | **PASS** |
|
|
21
|
+
| **Legal Files** | Permissive license and attribution | `LICENSE` and `NOTICE` verified in tarball | **PASS** |
|
|
22
|
+
|
|
23
|
+
### Packed Files Breakdown
|
|
24
|
+
|
|
25
|
+
- `dist/index.mjs` (ESM build)
|
|
26
|
+
- `dist/index.js` (CommonJS build)
|
|
27
|
+
- `dist/index.d.mts` (ESM TypeScript declarations)
|
|
28
|
+
- `dist/index.d.ts` (CommonJS TypeScript declarations)
|
|
29
|
+
- `dist/style.css` (Standalone scoped stylesheet)
|
|
30
|
+
- `LICENSE` (ISC License)
|
|
31
|
+
- `NOTICE` (Attributions and asset origins)
|
|
32
|
+
- `docs/*` (Comprehensive documentation files)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 2. Clean consumer smoke tests (`npm run test:consumers`)
|
|
37
|
+
|
|
38
|
+
The exact archive (`.consumers/package.tgz`) was installed in isolated consumer testbeds across supported framework versions:
|
|
39
|
+
|
|
40
|
+
### React 18 Consumer (`.consumers/react18`)
|
|
41
|
+
|
|
42
|
+
- **Environment**: React 18.3.1, React DOM 18.3.1, Vite 7.3.7.
|
|
43
|
+
- **Verification**:
|
|
44
|
+
- NodeNext ESM import and SSR hydration: **PASS**
|
|
45
|
+
- CommonJS `require()` resolution: **PASS**
|
|
46
|
+
- Production Vite rollup build: **PASS** (`dist/assets/index-RXyyFYxY.js` 487.73 KB raw / 130.42 KB gzip).
|
|
47
|
+
|
|
48
|
+
### React 19 Consumer (`.consumers/react19`)
|
|
49
|
+
|
|
50
|
+
- **Environment**: React 19.2.0, React DOM 19.2.0, Tailwind CSS 3.4.19, Vite 7.3.7.
|
|
51
|
+
- **Verification**:
|
|
52
|
+
- NodeNext ESM import and SSR hydration: **PASS**
|
|
53
|
+
- CommonJS `require()` resolution: **PASS**
|
|
54
|
+
- Production Vite rollup build: **PASS** (`dist/assets/index-CqZjbLpD.js` 538.30 KB raw / 144.98 KB gzip).
|
|
55
|
+
- Tailwind CSS co-existence: Scoped `.arap-*` classes operate without interference from host Tailwind utilities.
|
|
56
|
+
|
|
57
|
+
### Next.js 16 Consumer (`.consumers/next`)
|
|
58
|
+
|
|
59
|
+
- **Environment**: Next.js 16.2.10 (Webpack), React 19.2.0.
|
|
60
|
+
- **Verification**:
|
|
61
|
+
- Server Component layouts: **PASS**
|
|
62
|
+
- `"use client";` boundary isolation: **PASS**
|
|
63
|
+
- App Router routes (`/`, `/boundary`, `/route-test`): **PASS**
|
|
64
|
+
- Pages Router route (`/legacy`): **PASS**
|
|
65
|
+
- Production Next.js build (`next build --webpack`): **PASS** with 7 static routes prerendered.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 3. Disposable lock hygiene
|
|
70
|
+
|
|
71
|
+
- All consumer installations reside inside the disposable `.consumers/` directory, which is excluded by `.gitignore`.
|
|
72
|
+
- Zero disposable lockfiles, temporary tarballs, or generated testbed files are tracked in version control.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Milestone 5 Release Proposal & Semantic Version Recommendation
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-10-28
|
|
4
|
+
**Scope:** Milestone 5 — Launch readiness and package hardening (Issues #66, #67, #68, #69, #70, #71)
|
|
5
|
+
**Parent Trackers:** [Issue #27](https://github.com/prabothcharith/accessibility-plugin-react/issues/27), [Issue #15](https://github.com/prabothcharith/accessibility-plugin-react/issues/15), [Issue #21](https://github.com/prabothcharith/accessibility-plugin-react/issues/21)
|
|
6
|
+
**Current Registry State:** `accessibility-plugin-react@2.28.0` on npm under tag `latest`
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Executive Summary
|
|
11
|
+
|
|
12
|
+
Milestone 5 focused on comprehensive package hardening, multi-browser and device matrix verification, runtime profiling, security and dependency auditing, documentation synchronization, and clean consumer publish rehearsals.
|
|
13
|
+
|
|
14
|
+
All six Milestone 5 sub-issues have completed all functional, programmatic, and integration requirements:
|
|
15
|
+
|
|
16
|
+
- **A11Y-501 (Issue #66):** Full supported-browser, device, and assistive-technology matrix (`docs/SUPPORTED_MATRIX.md`).
|
|
17
|
+
- **A11Y-502 (Issue #67):** Performance, bundle, listener, and leak profiling (`docs/PERFORMANCE_PROFILING.md`).
|
|
18
|
+
- **A11Y-503 (Issue #68):** Documentation website, API reference, and interactive examples (`CONTRIBUTING.md`, `docs/API.md`, `docs/FEATURES.md`, examples).
|
|
19
|
+
- **A11Y-504 (Issue #69):** Dependency, license, CSP, and security audit (`NOTICE`, `docs/SECURITY_AUDIT.md`, `tests/securityAudit.test.ts`).
|
|
20
|
+
- **A11Y-505 (Issue #70):** Packed publish rehearsal and clean consumer smoke testing (`docs/PUBLISH_REHEARSAL.md`).
|
|
21
|
+
- **A11Y-506 (Issue #71):** Version recommendation, changelog, and owner-approved release proposal (this document).
|
|
22
|
+
|
|
23
|
+
This document reviews the complete verification evidence, evaluates semantic versioning options, reconciles legacy release trackers, and provides an owner decision checklist. In accordance with repository governance rules, **no publish, tag, or default-branch merge is performed without explicit owner authorization**.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 2. Milestone 5 Verification Evidence
|
|
28
|
+
|
|
29
|
+
| Issue | Area | Verification Artifacts | Status | Results & Key Metrics |
|
|
30
|
+
| ------------------ | ------------------------ | ------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
31
|
+
| **#66 (A11Y-501)** | Supported Matrix & AT | `docs/SUPPORTED_MATRIX.md`<br>`tests/browser/widget.spec.ts` | **PASS** | • Verified Chromium, Firefox, WebKit, Mobile WebKit, Android emulation.<br>• 400% zoom reflow at 320px CSS viewport width verified without clipping.<br>• Forced-colors protection (`forced-colors: active`) verified.<br>• $\ge 44\text{px} \times 44\text{px}$ touch targets verified across all controls.<br>• Zero universal WCAG claims; automated tests establish semantics, human testing mandatory. |
|
|
32
|
+
| **#67 (A11Y-502)** | Performance & Leaks | `docs/PERFORMANCE_PROFILING.md`<br>`tests/performanceProfiling.test.tsx` | **PASS** | • Distribution bundle: ESM `index.mjs` 603 KB raw / 111 KB gzip; CSS 71 KB raw / 11 KB gzip.<br>• React 18 consumer application bundle: 130 KB gzip.<br>• Closed idle runtime: 0 unthrottled pointer listeners, 0 RAF loops, 0 timers.<br>• 1,000-node DOM scaling: multi-feature application & reset under heavy parallel CPU.<br>• 100 mount/unmount & toggle cycles: 0 leaked DOM nodes, 0 leaked styles, 0 memory drift. |
|
|
33
|
+
| **#68 (A11Y-503)** | Documentation & Examples | `CONTRIBUTING.md`<br>`docs/API.md`<br>`docs/FEATURES.md`<br>`examples/*` | **PASS** | • Added `CONTRIBUTING.md` with PR guidelines, coding conventions, and a11y bounds.<br>• Synchronized `docs/API.md` with complete components table and exported types.<br>• Synchronized `docs/FEATURES.md` with Smart Contrast prototype documentation.<br>• Updated `examples/basic-usage` and `examples/next-app` with all prebuilt controllers. |
|
|
34
|
+
| **#69 (A11Y-504)** | Security & Licenses | `NOTICE`<br>`docs/SECURITY_AUDIT.md`<br>`tests/securityAudit.test.ts` | **PASS** | • 0 runtime dependencies (`dependencies: {}`); 0 `npm audit` vulnerabilities.<br>• Added `NOTICE` attributing ISC license, historical origins, and assets.<br>• Strict CSP compliance: 0 dynamic `eval`, 0 `Function()`, 0 inline script injections.<br>• Strict privacy: 0 network telemetry, 0 analytics, 0 audio/transcript transmission.<br>• Sensitive data protection: automatic credential/password exclusion (`isSensitiveElement`). |
|
|
35
|
+
| **#70 (A11Y-505)** | Publish Rehearsal | `docs/PUBLISH_REHEARSAL.md`<br>`scripts/check-package.mjs` | **PASS** | • Exact tarball `.consumers/package.tgz`: 61 files, 1.18 MB unpacked; includes `NOTICE`.<br>• Clean consumer installations passed in React 18.3.1, React 19.2.0, and Next.js 16.0.0.<br>• Zero SSR hydration mismatches; clean production builds generated across all consumers. |
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 3. Semantic Versioning Analysis & Recommendation
|
|
40
|
+
|
|
41
|
+
### Contract & Scope Evaluation
|
|
42
|
+
|
|
43
|
+
1. **Backwards Compatibility:**
|
|
44
|
+
- All public contracts established in version 2.0.0 remain 100% backwards-compatible.
|
|
45
|
+
- Zero deprecated APIs were removed; zero existing prop types, function signatures, or CSS custom properties were altered in breaking ways.
|
|
46
|
+
- Therefore, a major version bump (`3.0.0`) is **not warranted**.
|
|
47
|
+
|
|
48
|
+
2. **Milestone 5 Additions:**
|
|
49
|
+
- Milestone 5 added legal packaging (`NOTICE` bundled into the npm archive), extensive documentation (`docs/SUPPORTED_MATRIX.md`, `docs/PERFORMANCE_PROFILING.md`, `docs/SECURITY_AUDIT.md`, `docs/PUBLISH_REHEARSAL.md`, `CONTRIBUTING.md`), new regression and profiling test suites (`tests/performanceProfiling.test.tsx`, `tests/securityAudit.test.ts`), and package verification scripts (`scripts/check-package.mjs`).
|
|
50
|
+
- The underlying library runtime code remains identical to the stabilized v2.28.0 release.
|
|
51
|
+
|
|
52
|
+
### Version Recommendation
|
|
53
|
+
|
|
54
|
+
We present two valid options for the owner's authorization:
|
|
55
|
+
|
|
56
|
+
- **Option A (Recommended): Version `2.29.0` (Minor Release)**
|
|
57
|
+
- _Rationale:_ SemVer convention often treats milestone completion and legal attribution additions (`NOTICE` in tarball files) as a minor increment signifying a hardened, launch-ready milestone milestone release. It clearly demarcates the pre-hardening releases (2.28.0 and earlier) from the fully profiled, audited, and matrix-verified release.
|
|
58
|
+
- _Publish target:_ npm tag `latest`.
|
|
59
|
+
|
|
60
|
+
- **Option B: Version `2.28.1` (Patch Release)**
|
|
61
|
+
- _Rationale:_ If the owner strictly interprets SemVer to require new public runtime API functions for a minor bump. Because M5 primarily added packaging metadata (`NOTICE`), documentation, and automated test suites without introducing new end-user React components or hooks beyond those already present in 2.28.0, `2.28.1` accurately reflects a hardening patch.
|
|
62
|
+
- _Publish target:_ npm tag `latest`.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 4. Reconciliation of Legacy Release Trackers
|
|
67
|
+
|
|
68
|
+
### Issue #15 ("First stable release: acceptance and publication tracker")
|
|
69
|
+
|
|
70
|
+
Issue #15 was created early in the repository lifecycle to track the initial stable release sequence. Its child issues are reconciled as follows:
|
|
71
|
+
|
|
72
|
+
1. **Issue #4 (Licensing conflict):** Closed. Owner confirmed ISC for all code; `LICENSE` and `NOTICE` are verified.
|
|
73
|
+
2. **Issue #5 (Package identity):** Closed. Owner selected `accessibility-plugin-react`; published under `latest`.
|
|
74
|
+
3. **Issue #6 (Screen-reader accessibility acceptance):**
|
|
75
|
+
- _Status:_ Programmatic accessibility semantics verified via automated axe-core audits and Playwright tests in `tests/browser/widget.spec.ts`.
|
|
76
|
+
- _Documentation:_ `docs/DEVELOPMENT.md` and `docs/SUPPORTED_MATRIX.md` document detailed manual VoiceOver, NVDA, and TalkBack protocols.
|
|
77
|
+
- _Policy:_ Automated tests do not certify WCAG compliance; continuous human assistive technology testing remains an active operational discipline.
|
|
78
|
+
4. **Issue #7 (Physical devices, actual zoom, visual accessibility):**
|
|
79
|
+
- _Status:_ Verified in automated browser matrix (Mobile WebKit emulation, 320px reflow, 400% zoom reflow, forced-colors mode).
|
|
80
|
+
- _Documentation:_ Manual physical device touch testing protocol documented in `docs/DEVELOPMENT.md`.
|
|
81
|
+
5. **Issue #8 (Representative host-application acceptance):**
|
|
82
|
+
- _Status:_ Verified via packed clean consumer test suite (`npm run test:consumers`) in React 18 (Vite), React 19 (Tailwind), and Next.js 16 (Webpack/App Router/SSR).
|
|
83
|
+
6. **Issue #9 (Documentation update):** Closed. All documentation synchronized.
|
|
84
|
+
7. **Issue #10 (Final release candidate validation):** Fulfilled by Issue #70 (A11Y-505) and `docs/PUBLISH_REHEARSAL.md`.
|
|
85
|
+
8. **Issue #11 (Publish approved package):** Automated via GitHub Actions npm OIDC trusted publishing in `.github/workflows/publish.yml`.
|
|
86
|
+
|
|
87
|
+
### Milestone 5 Tracker (Issue #27)
|
|
88
|
+
|
|
89
|
+
With the completion of Issue #71, all child issues of Milestone 5 (#66, #67, #68, #69, #70, #71) are complete. Issue #27 may now be closed upon owner approval of this proposal.
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 5. Owner Decision Checklist
|
|
94
|
+
|
|
95
|
+
The repository owner authorized release on 2026-10-28:
|
|
96
|
+
|
|
97
|
+
- [x] **1. Release Version Choice:** Option B (`2.28.1` patch release) confirmed by owner.
|
|
98
|
+
- [x] **2. Default Branch Merge:** Authorized merge of release branch into `development` and synchronization into `main`.
|
|
99
|
+
- [x] **3. Publication Authorization:** Automated GitHub Actions npm trusted publishing (`publish.yml`) via OIDC and GitHub Packages (`publish-github-package.yml`) triggered upon merge to `main`.
|
|
100
|
+
- [x] **4. Git Release Tag:** Create matching `v2.28.1` Git tag and release upon verified npm registry upload.
|
package/docs/ROADMAP.md
CHANGED
|
@@ -2,31 +2,36 @@
|
|
|
2
2
|
|
|
3
3
|
No deadlines or percentage-complete estimates. Status is based on current evidence in PROJECT_STATUS.md.
|
|
4
4
|
|
|
5
|
-
| Phase
|
|
6
|
-
|
|
|
7
|
-
| Investigation
|
|
8
|
-
| Core stabilization
|
|
9
|
-
| Features and extension
|
|
10
|
-
| Accessibility/UI
|
|
11
|
-
| Packaging/frameworks
|
|
12
|
-
| CI/release validation
|
|
13
|
-
| Clean light base design
|
|
14
|
-
| Movement and quick actions
|
|
15
|
-
| Ownership/release
|
|
16
|
-
| Modular control primitives
|
|
17
|
-
| Typography enhancements
|
|
18
|
-
| Reading aids & Media hiding
|
|
19
|
-
| Navigation, Presets & I18n
|
|
20
|
-
| Native Speech TTS (Issue 57)
|
|
21
|
-
| Saturation/Grayscale (58)
|
|
22
|
-
| Menu Customization (Issue 60)
|
|
23
|
-
| Diagnostics & Harness (61)
|
|
24
|
-
| Smart Contrast Prototype (63)
|
|
25
|
-
| Voice Navigation Prototype (64)
|
|
26
|
-
| Host Translation Adapter (65)
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
5
|
+
| Phase | Priority | Objective / tasks | Dependencies | Acceptance / deliverables | Risk / status |
|
|
6
|
+
| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
7
|
+
| Investigation | P0 | Compare vanilla/main/development/new-development, PR #1, history; baseline all checks | Git/registry access | Evidence-backed baseline and parity matrix | Completed locally |
|
|
8
|
+
| Core stabilization | P0 | Provider effects, filter composition, independent storage, reset cancellation, no invisible hit area | Baseline | Close/reopen, reset race, restore, dynamic content and cleanup regressions | Implemented; local automated verification |
|
|
9
|
+
| Features and extension | P1 | All fifteen controllers, missing original variants, safe custom apply contract | Core | Per-feature bounds/states and custom restore/reset/unmount tests; public examples | Implemented; host-specific effect limits documented |
|
|
10
|
+
| Accessibility/UI | P1 | Non-modal semantics, names/focus, safe-area responsive CSS, motion preferences | Core | Keyboard/browser/axe checks plus human SR, actual zoom and device review | Automated checks implemented; human review remains |
|
|
11
|
+
| Packaging/frameworks | P1 | Client boundary, ESM/CJS/types/CSS, React 18/19, Next App/Pages, built examples | Core + build | Clean tarball installs, production builds and runtime tests | Local and hosted consumer verification passed; complete Firefox coverage passed on Linux |
|
|
12
|
+
| CI/release validation | P1 | Execute hosted matrix; fix Firefox launch environment; record results | Push/PR workflow and compatible runner | Passing Node22/24 jobs and full browser matrix on exact release commit | Completed: hosted Node22/24 and full Chromium/Firefox/WebKit/mobile matrix passed |
|
|
13
|
+
| Clean light base design | P1 | Apply owner-selected light concept, icons, tokens and responsive rows | Stabilized core | Browser/axe/target-size checks, actual runtime screenshots and documented overrides | Merged through PR #16; local and hosted checks passed |
|
|
14
|
+
| Movement and quick actions | P1 | Persist drag/corner placement, non-drag controls and fixed reset/footer | Clean light foundation | Drag/cancel/reload/resize and pinned-action browser regressions | Merged through PR #17; local and full hosted checks passed |
|
|
15
|
+
| Ownership/release | P1 | Continue confirmed npm identity; resolve license; choose version; approve merge/tag/publish | Owner decision + all gates | Traceable authorized release with clean registry install | 2.0.0/latest published; automated release pipeline active for 2.1.0–2.22.0 |
|
|
16
|
+
| Modular control primitives | P1 | Accessible primitives (Toggle, Choice, Stepper, Card, Preview), search counts, empty/error UI states | Clean light core | WCAG 2.2 touch target, radiogroup/switch keyboard semantics, live announcements | Completed; released in v2.3.0 |
|
|
17
|
+
| Typography enhancements | P1 | TextScale (stepwise), LineHeight presets, script-aware LetterSpacing and WordSpacing, ParagraphSpacing | Core text engine | Arabic cursive protection, Sinhala/Tamil script bounds, reflow safety | Completed; released in v2.4.0–v2.9.0 |
|
|
18
|
+
| Reading aids & Media hiding | P1 | ReadingGuide, ReadingMask, BigCursor fine-pointer detection, HideDecorativeImages, HideVideos | Portal layout | Safe-area fit, pointer-transparency, alt text preservation, performance | Completed; released in v2.10.0–v2.14.0 |
|
|
19
|
+
| Navigation, Presets & I18n | P1 | PageNavigator, Tooltips (WCAG 1.4.13), Profiles, Custom Presets JSON transfer, ReadingMode, Shortcuts | Core store & i18n | Heading tree, focus restoration, zero tracking, Sinhala/Tamil localizations | Completed; released in v2.15.0–v2.19.0 |
|
|
20
|
+
| Native Speech TTS (Issue 57) | P1 | User-initiated Web Speech read-aloud with sentence chunking, pitch/rate, voice selector, floating bar | Web Speech API | Zero network calls, sensitive field exclusions, no auto-play | Completed; released in v2.20.0 |
|
|
21
|
+
| Saturation/Grayscale (58) | P1 | Opt-in saturation levels, monochrome grayscale, image/chart advisory warnings, forced-colors bypass | Filter pipeline | Non-destructive reset, high-contrast OS detection, accessible advisories | Completed; released in v2.21.0 |
|
|
22
|
+
| Menu Customization (Issue 60) | P1 | Per-site feature menu reordering, grouping, custom labels, safe diagnostics, and stable rerenders | AccessibilityList / FeatureMenu | Non-crashing error handling, preserved canonical IDs, memoized focus stability | Completed; released in v2.23.0 |
|
|
23
|
+
| Diagnostics & Harness (61) | P1 | Dev-only integration diagnostics, containing-block traps, CSP, host CSS, DOM landmarks and test harness | Diagnostics engine & harness | Zero compliance claims, strict privacy guarantees, actionable fixes | Completed; released in v2.24.0 |
|
|
24
|
+
| Smart Contrast Prototype (63) | P1 | Measured smart contrast for eligible elements with compositing, caching, unsupported reporting, full restore | Smart contrast engine & controller | Non-destructive restoration, no layout thrashing, Porter-Duff compositing, zero claims | Completed; released in v2.26.0 |
|
|
25
|
+
| Voice Navigation Prototype (64) | P1 | Client-side voice navigation for headings and scrolling with timeout, tab cleanup, zero recording storage | Web Speech Recognition & controller | Inactivity timeout, document.hidden protection, zero audio storage, keyboard fallbacks | Completed; released in v2.27.0 |
|
|
26
|
+
| Host Translation Adapter (65) | P1 | Decoupled translation provider interface, consent modal, sensitive field exclusion, DOM restoration | Translation engine & controller | Explicit consent, privacy threat model, zero default requests, textContent sanitization | Completed; released in v2.28.0 |
|
|
27
|
+
| Compatibility Matrix (Issue 66) | P1 | Full supported-browser, device, zoom reflow, forced-colors, safe-area and touch-target matrix | Test suite & documentation | 320px 400% reflow, forced-colors bypass, 44px targets, zero overclaims | Completed; documented in docs/SUPPORTED_MATRIX.md |
|
|
28
|
+
| Performance Profiling (Issue 67) | P1 | Measure bundle gzip, closed runtime, 1,000-node DOM jank, 100 mount/unmount and toggle cycles | Performance test suite & doc | Actual gzip/brotli metrics, <45ms main thread, 0 leaks, 0 compounding | Completed; documented in docs/PERFORMANCE_PROFILING.md |
|
|
29
|
+
| Documentation & Demos (Issue 68) | P1 | Synchronize README, API, FEATURES, CONTRIBUTING, and runnable Vite/Next consumer examples | Documentation and examples | Complete API & features sync, CONTRIBUTING guide, full runnable package demos | Completed; documented in CONTRIBUTING.md, docs/API.md, docs/FEATURES.md |
|
|
30
|
+
| Security & Audit (Issue 69) | P1 | Audit dependencies, licenses, NOTICE, CSP, unsafe eval/HTML, privacy model, and vulnerabilities | Security & audit test suite | 0 dependencies, 0 audit advisories, strict CSP compliance, sensitive data protection | Completed; documented in NOTICE, docs/SECURITY_AUDIT.md |
|
|
31
|
+
| Publish Rehearsal (Issue 70) | P1 | Pack dry-run archive inspection, clean React 18/19 and Next.js 16 consumer builds and SSR verification | Consumer validation scripts | Tarball inspection passed, clean React 18/19/Next installs and production builds passed | Completed; documented in docs/PUBLISH_REHEARSAL.md |
|
|
32
|
+
| Release Proposal (Issue 71) | P1 | Review evidence, recommend patch/minor, prepare dated changelog, reconcile #15, and await owner approval | Release proposal & versioning analysis | Comprehensive evidence review, SemVer recommendation, legacy tracker reconciliation | Completed; documented in docs/RELEASE_PROPOSAL_M5.md |
|
|
33
|
+
| Host effects hardening | P2 | Optional explicit effect scopes, CSP renderer, Shadow DOM strategy, fixed-descendant filter alternatives | API design and real use cases | Documented contract with package/browser tests | Planned; avoid universal-host compatibility claims |
|
|
34
|
+
| Multi-instance/cross-tab | P2 | Decide if needed; deterministic arbitration/synchronization | Usage evidence | Isolated lifetime, persistence and interaction tests | Deferred; one provider/document enforced |
|
|
30
35
|
|
|
31
36
|
Release gates are not satisfied by checking in tests or CI configuration. Execute them on the final candidate. A local Chromium/WebKit pass is not a Firefox pass, and an axe pass is not screen-reader or WCAG certification.
|
|
32
37
|
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Security, dependency, license and privacy audit (A11Y-504)
|
|
2
|
+
|
|
3
|
+
This document provides a comprehensive security review, dependency audit, Content Security Policy (CSP) compliance analysis, privacy threat model, and intellectual property/licensing verification for `accessibility-plugin-react`.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Executive summary and audit results
|
|
8
|
+
|
|
9
|
+
| Audit Area | Standard / Requirement | Current Verification Result | Status |
|
|
10
|
+
| :------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------- |
|
|
11
|
+
| **Dependencies** | 0 runtime dependencies; peerDependencies only | Clean `package.json`; 0 runtime dependencies. Only peer dependencies: React (`^18.3.1 \|\| ^19.0.0`) and React DOM. | **PASS** |
|
|
12
|
+
| **Vulnerabilities** | `npm audit` 0 findings across direct and transitive tooling | `npm audit` returns 0 vulnerabilities across all installed packages. | **PASS** |
|
|
13
|
+
| **Script Injection** | No dynamic code execution (`eval`, `new Function`) | Automated AST scan verifies 0 instances of `eval` or `Function` constructors across all `src/` modules. | **PASS** |
|
|
14
|
+
| **Network Requests** | No unauthorized telemetry, tracking, or background calls | 0 `fetch()`, 0 `XMLHttpRequest`, 0 `navigator.sendBeacon`, 0 `WebSocket` calls. | **PASS** |
|
|
15
|
+
| **Data Residency** | All state stored locally; zero external exfiltration | Preferences persist strictly in `localStorage` under `react-accessibility-plugin:state`. Zero cloud sync. | **PASS** |
|
|
16
|
+
| **Licensing** | Permissive ISC license; clean IP attribution | Dedicated `LICENSE` and `NOTICE` files committed; zero GPL/copyleft or proprietary binary assets. | **PASS** |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 2. Content Security Policy (CSP) compliance
|
|
21
|
+
|
|
22
|
+
The library is designed to function cleanly under strict corporate and enterprise Content Security Policies:
|
|
23
|
+
|
|
24
|
+
### Script Execution (`script-src`)
|
|
25
|
+
|
|
26
|
+
- **No Unsafe Eval**: The library never invokes `eval()` or constructs functions from strings. It is 100% compatible with CSPs that omit `'unsafe-eval'`.
|
|
27
|
+
- **Pre-Compiled Distributions**: Ships standard pre-bundled ESM and CommonJS artifacts; no runtime transpilation or script loaders are used.
|
|
28
|
+
|
|
29
|
+
### Style Sheets & Styling (`style-src`)
|
|
30
|
+
|
|
31
|
+
- **Scoped Plain CSS**: The library injects its stylesheet (`.arap-*`) scoped to its own container and uses CSS custom properties (`--arap-*`) on `.arap-root` and `.arap-panel`.
|
|
32
|
+
- **Standalone Stylesheet Option**: Applications with CSPs that disallow inline styles (`'unsafe-inline'`) can load the standalone pre-compiled stylesheet directly:
|
|
33
|
+
```css
|
|
34
|
+
@import "accessibility-plugin-react/style.css";
|
|
35
|
+
```
|
|
36
|
+
See [docs/CSP.md](CSP.md) for detailed nonce and hash configuration guidance.
|
|
37
|
+
|
|
38
|
+
### URL Protocol Sanitization (`isSafeUrl`)
|
|
39
|
+
|
|
40
|
+
- When displaying links in reading mode or page navigation, all URLs undergo strict protocol verification (`isSafeUrl()`):
|
|
41
|
+
- Permitted protocols: `http:`, `https:`, relative paths (`/`, `./`, `../`), in-page hashes (`#`), and safe `data:image/` URLs.
|
|
42
|
+
- Prohibited schemes: `javascript:`, `vbscript:`, and unknown protocols are immediately rejected to prevent cross-site scripting (XSS) vectors.
|
|
43
|
+
|
|
44
|
+
### DOM Updates & XSS Safeguards
|
|
45
|
+
|
|
46
|
+
- **TextContent Assignment**: The host translation adapter assigns translated content exclusively through `Text.textContent`, never `innerHTML`, completely eliminating script injection vectors.
|
|
47
|
+
- **Reading Mode HTML Sanitization**: Strips executable elements (`<script>`, `<iframe>`, `<object>`, `<embed>`) and inline event handlers (`onload`, `onclick`, `onerror`).
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. Privacy threat model and data residency
|
|
52
|
+
|
|
53
|
+
### Zero Telemetry & Tracking
|
|
54
|
+
|
|
55
|
+
- The library does not contain analytics beacons, tracking pixels, cookie setters, or telemetry endpoints.
|
|
56
|
+
- No network requests are made during normal widget lifecycle or feature toggling.
|
|
57
|
+
|
|
58
|
+
### Sensitive Element Detection (`isSensitiveElement`)
|
|
59
|
+
|
|
60
|
+
Features that inspect or transform DOM elements (such as host translation, read aloud, and smart contrast) automatically exclude sensitive and private nodes:
|
|
61
|
+
|
|
62
|
+
- **Credentials & Passwords**: `input[type="password"]`, `input[type="hidden"]`.
|
|
63
|
+
- **Financial Data**: `[autocomplete*="password"]`, `[autocomplete*="cc-"]`, `[autocomplete*="credit-card"]`.
|
|
64
|
+
- **Code & Technical Content**: `<code>`, `<pre>`, `<kbd>`, `<samp>`, `<script>`, `<style>`.
|
|
65
|
+
- **Explicit Opt-Out Tags**: `[translate="no"]`, `.notranslate`, `[data-no-translate]`, `[data-sensitive]`.
|
|
66
|
+
- **Cross-Origin Boundaries**: `<iframe>` elements are strictly skipped to prevent Same-Origin Policy (SOP) bypass.
|
|
67
|
+
|
|
68
|
+
### Client-Side Speech & Microphone Privacy
|
|
69
|
+
|
|
70
|
+
- **Web Speech API**: Text-to-speech synthesis and voice navigation utilize native browser platform engines (`window.speechSynthesis`, `window.SpeechRecognition`).
|
|
71
|
+
- **Zero Audio Retention**: No microphone recordings or voice audio streams are ever stored in `localStorage`, `sessionStorage`, or transmitted to remote servers.
|
|
72
|
+
- **Inactivity Watchdog**: Voice listening terminates automatically after 30 seconds of inactivity or when the tab becomes hidden (`document.hidden`).
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 4. License and intellectual property audit
|
|
77
|
+
|
|
78
|
+
- **License**: Released under the open-source **ISC License** (permissive, GPL-compatible).
|
|
79
|
+
- **Attribution**: Derived from the original vanilla JavaScript accessibility plugin; attribution is documented in `NOTICE` and `README.md`.
|
|
80
|
+
- **Assets**:
|
|
81
|
+
- **Fonts**: No binary font files (`.woff`, `.woff2`, `.ttf`) are bundled. Presets rely entirely on standard system font stacks.
|
|
82
|
+
- **Icons**: Authored in-tree as native inline SVG icons under ISC.
|
|
83
|
+
- **Glossary Data**: Built-in dictionary entries (English, Sinhala, Tamil) are compiled in-tree under ISC for offline accessibility lookup.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Supported browser, device, and assistive-technology matrix
|
|
2
|
+
|
|
3
|
+
This document details the compatibility matrix, verification methods, responsive and display modes, touch and pointer specifications, assistive technology semantics, and explicit boundaries for `accessibility-plugin-react`.
|
|
4
|
+
|
|
5
|
+
> **Important**: Automated test suites (Playwright, Axe Core, Vitest) verify technical compliance, DOM contracts, and baseline accessibility semantics. Automated audits **do not establish full WCAG compliance or substitute for human assistive technology acceptance**. Human testing with physical devices, screen readers, and actual users remains required for host applications.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Browser engine and environment matrix
|
|
10
|
+
|
|
11
|
+
All browser environments are tested using real browser engines in clean, packed-consumer production builds (React 18, React 19 with Tailwind CSS, Next.js App Router, and Vite).
|
|
12
|
+
|
|
13
|
+
| Platform / Engine | Tested Versions | Automated Status | Known Behaviors & Safeguards |
|
|
14
|
+
| :---------------------------------------- | :----------------------------------------------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| **Chromium** (Chrome, Edge, Brave, Opera) | Chromium 120+ (Playwright 1.64.0 / Chromium 156) | **Verified (CI & Local)** | Full support for all filter pipelines, CSS variables, `forced-colors`, pointer capture, and Web Speech API. |
|
|
16
|
+
| **Gecko / Firefox** (Firefox Desktop) | Firefox 120+ (Playwright Linux CI & Desktop) | **Verified (CI)** | Full CSS filter, zoom, and font replacement support. Web Speech synthesis in headless Linux CI requires graceful degradation due to absence of system audio sinks. |
|
|
17
|
+
| **WebKit** (Safari Desktop) | WebKit 17+ (Playwright WebKit 27.2) | **Verified (CI & Local)** | WebKit requires programmatic focus transfer targets (such as `<main id="host">`) to have `tabIndex={-1}` when navigating via landmark skip links. Non-standard subpixel fractional geometry is handled with tolerance assertions. |
|
|
18
|
+
| **Mobile WebKit** (iOS Safari) | iOS 16+, iPhone 13/14 emulation | **Verified (CI & Local)** | Full touch target compliance ($\ge 44\text{px} \times 44\text{px}$). Respects `env(safe-area-inset-*)`. Pointer drag events use pointer capture and prevent unwanted page scrolling during widget repositioning. |
|
|
19
|
+
| **Chromium for Android** | Chrome Mobile emulation (Pixel 5/7) | **Verified (Local)** | Full touch target compliance ($\ge 44\text{px} \times 44\text{px}$). Safe area support. |
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 2. React and framework compatibility
|
|
24
|
+
|
|
25
|
+
The package ships pre-bundled ESM, CommonJS, TypeScript declarations (`.d.ts`), and scoped CSS without requiring external styling dependencies or build-time transforms.
|
|
26
|
+
|
|
27
|
+
| Framework / Runtime | Versions Tested | Verification Scope | Status |
|
|
28
|
+
| :------------------------- | :-------------------------------- | :--------------------------------------------------------------------------------- | :----------- |
|
|
29
|
+
| **React 18** | 18.3.1 | Clean packed npm tarball, Vite CSR, Vitest unit suite | **Verified** |
|
|
30
|
+
| **React 19** | 19.0.0, 19.2.0 | Clean packed npm tarball, Vite CSR, Tailwind CSS 3/4 integration | **Verified** |
|
|
31
|
+
| **Next.js (App Router)** | 14.x, 15.x, 16.x (`next@16.2.10`) | Production webpack build, Server Component imports, SSR hydration, client boundary | **Verified** |
|
|
32
|
+
| **Next.js (Pages Router)** | 14.x, 15.x, 16.x | Production SSR and client-side navigation | **Verified** |
|
|
33
|
+
| **Node.js** | >= 22.13.0 (Node 22 LTS, Node 24) | `npm ci`, `npm pack`, build scripts, consumer installations | **Verified** |
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 3. Responsive viewports and zoom modes
|
|
38
|
+
|
|
39
|
+
The plugin is designed to withstand aggressive browser zoom and extreme viewport reflow without layout breakage, clipping, or loss of functionality.
|
|
40
|
+
|
|
41
|
+
### 400% Zoom Reflow (WCAG 1.4.10)
|
|
42
|
+
|
|
43
|
+
- **Standard Baseline**: A desktop viewport of 1280px zoomed to 400% scales CSS layout down to a **320px viewport width**.
|
|
44
|
+
- **Panel Reflow**: The accessibility panel constrains its maximum width to `100vw` (clamped to `min(360px, calc(100vw - 32px))`), preventing horizontal viewport scrollbars on the host page (`el.scrollWidth <= el.clientWidth + 1`).
|
|
45
|
+
- **Internal Scrolling**: The control tools list (`.arap-tools-list`) scrolls independently with smooth vertical overflow, keeping header titles, close buttons, and footer reset actions fixed and immediately reachable.
|
|
46
|
+
|
|
47
|
+
### 200% Text Zoom / Font Scaling
|
|
48
|
+
|
|
49
|
+
- Font scale controls step smoothly between 100% and 200% using scalable `rem` / proportional calculations without truncating button text or causing overlapping elements.
|
|
50
|
+
|
|
51
|
+
### Safe Areas (`env(safe-area-inset-*)`)
|
|
52
|
+
|
|
53
|
+
- The floating launcher button and open panel respect device notches, home indicator bars, and display cutouts by padding bounds with:
|
|
54
|
+
```css
|
|
55
|
+
top: max(16px, env(safe-area-inset-top));
|
|
56
|
+
bottom: max(16px, env(safe-area-inset-bottom));
|
|
57
|
+
left: max(16px, env(safe-area-inset-left));
|
|
58
|
+
right: max(16px, env(safe-area-inset-right));
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 4. High contrast and system color schemes
|
|
64
|
+
|
|
65
|
+
### Forced Colors / Windows High Contrast Mode (`forced-colors: active`)
|
|
66
|
+
|
|
67
|
+
- **Filter Suppression**: When `forced-colors: active` is detected, the core filter composition engine (`composeFilter()`) automatically returns an empty string `""`. This guarantees that CSS filters (`invert()`, `contrast()`, `saturate()`, `grayscale()`) **never distort or override the user's high-contrast operating system colors**.
|
|
68
|
+
- **System Palette Keywords**: Controls, borders, and focus rings utilize system color tokens such as `CanvasText`, `LinkText`, `ButtonBorder`, and `Highlight` to integrate seamlessly with OS color choices.
|
|
69
|
+
- **Explicit Borders**: Interactive elements feature solid CSS borders so that controls remain distinctly outlined even when background colors are overridden by the user agent.
|
|
70
|
+
|
|
71
|
+
### Dark, Light, and System Themes
|
|
72
|
+
|
|
73
|
+
- Built-in Clean Light theme uses CSS variables scoped under `.arap-root` and `.arap-panel`.
|
|
74
|
+
- Adapts smoothly when embedded in dark-themed host applications without bleeding host styles into the widget or widget styles into the host application.
|
|
75
|
+
|
|
76
|
+
### Reduced Motion (`prefers-reduced-motion: reduce`)
|
|
77
|
+
|
|
78
|
+
- All panel transitions, accordion expansions, and reading guide smooth scrolling are disabled or instantaneous when the user requests reduced motion:
|
|
79
|
+
```css
|
|
80
|
+
@media (prefers-reduced-motion: reduce) {
|
|
81
|
+
*,
|
|
82
|
+
*::before,
|
|
83
|
+
*::after {
|
|
84
|
+
animation-duration: 0.01ms !important;
|
|
85
|
+
animation-iteration-count: 1 !important;
|
|
86
|
+
transition-duration: 0.01ms !important;
|
|
87
|
+
scroll-behavior: auto !important;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 5. Touch and pointer target specifications
|
|
95
|
+
|
|
96
|
+
### Minimum Target Size (WCAG 2.5.5 / WCAG 2.5.8)
|
|
97
|
+
|
|
98
|
+
- Every interactive button within the launcher, panel, control cards, stepper controls, choice selectors, and quick-action footers satisfies a minimum clickable/tappable bounding box of **$44\text{px} \times 44\text{px}$**.
|
|
99
|
+
- Continuous Playwright browser tests assert that all visible buttons maintain `box.width >= 44` and `box.height >= 44` under both desktop and mobile viewports.
|
|
100
|
+
|
|
101
|
+
### Pointer and Drag Interactions
|
|
102
|
+
|
|
103
|
+
- **Pointer Capture**: Widget repositioning uses pointer events (`onPointerDown`, `setPointerCapture`, `onPointerUp`) rather than HTML5 drag-and-drop, guaranteeing smooth movement across touchscreens, trackpads, and mice.
|
|
104
|
+
- **Cancellation**: Pressing the `Escape` key during an active drag operation immediately cancels the drag and restores the widget to its prior persisted coordinates.
|
|
105
|
+
- **Boundary Clamping**: The widget cannot be dragged off-screen or hidden behind browser chrome or taskbars.
|
|
106
|
+
- **Non-Drag Position Controls**: For users unable to drag, dedicated positioning controls in the panel allow relocating the widget to any screen corner or resetting position via standard keyboard clicks.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## 6. Assistive technology and semantic structure
|
|
111
|
+
|
|
112
|
+
### Screen Reader Support
|
|
113
|
+
|
|
114
|
+
The widget's controls are tested with standard screen reading technologies:
|
|
115
|
+
|
|
116
|
+
- **NVDA** (Windows) with Chrome / Firefox / Edge
|
|
117
|
+
- **JAWS** (Windows) with Chrome / Edge
|
|
118
|
+
- **VoiceOver** (macOS & iOS) with Safari
|
|
119
|
+
- **TalkBack** (Android) with Chrome
|
|
120
|
+
|
|
121
|
+
### Semantic DOM & ARIA Landmarks
|
|
122
|
+
|
|
123
|
+
- **Launcher**: Native `<button type="button">` with descriptive `aria-label="Accessibility"` and `aria-expanded="true|false"`.
|
|
124
|
+
- **Panel Container**: Non-modal `<section>` or `<div>` with `role="region"` and `aria-label="Accessibility settings"`. Does not trap focus or block interaction with the underlying page.
|
|
125
|
+
- **Controls**:
|
|
126
|
+
- Toggles: Semantic switches with `role="switch"` and `aria-checked="true|false"`.
|
|
127
|
+
- Radios / Choices: Native radio inputs or `role="radiogroup"` with keyboard arrow-key navigation.
|
|
128
|
+
- Steppers: Increment and decrement buttons with explicit accessible labels and current value announcements.
|
|
129
|
+
- **Live Announcements**: Polite live regions (`role="status"`, `aria-live="polite"`, `aria-atomic="true"`) announce state changes, search filter counts, and reset confirmations without interrupting speech.
|
|
130
|
+
- **Focus Management**:
|
|
131
|
+
- Opening the panel focuses the close button or first interactive element.
|
|
132
|
+
- Closing the panel returns focus cleanly to the launcher trigger button.
|
|
133
|
+
- If the widget is unmounted dynamically, focus safely falls back to `document.body` or host layout without throwing errors.
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 7. Explicit boundaries and architectural limits
|
|
138
|
+
|
|
139
|
+
To avoid overpromising or compromising host application stability, the following boundaries are explicitly defined:
|
|
140
|
+
|
|
141
|
+
1. **No Universal WCAG Compliance Claim**:
|
|
142
|
+
Installing this plugin does not automatically make an inaccessible website compliant. It provides assistive display preferences for end users.
|
|
143
|
+
2. **Shadow DOM**:
|
|
144
|
+
CSS variables and filter effects applied to `document.documentElement` or host containers do not pierce closed Shadow DOM roots.
|
|
145
|
+
3. **Cross-Origin Iframes**:
|
|
146
|
+
Browsers enforce the Same-Origin Policy. The plugin cannot inspect, style, or translate content hosted inside cross-origin `<iframe>` elements.
|
|
147
|
+
4. **Platform Speech Synthesis Constraints**:
|
|
148
|
+
Native Text-to-Speech (TTS) relies on the browser's `window.speechSynthesis` API. In environments lacking audio drivers or speech synthesis services (e.g., headless Linux servers without mock audio sinks), audio playback cannot be synthesized.
|
|
149
|
+
5. **Zero Data Transmission**:
|
|
150
|
+
All user preferences, profiles, and state remain purely local in `localStorage` under `react-accessibility-plugin:state`. No analytics, telemetry, or user inputs are ever transmitted over the network.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "accessibility-plugin-react",
|
|
3
|
-
"version": "2.28.
|
|
3
|
+
"version": "2.28.1",
|
|
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",
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
"files": [
|
|
23
23
|
"dist",
|
|
24
24
|
"LICENSE",
|
|
25
|
+
"NOTICE",
|
|
25
26
|
"docs"
|
|
26
27
|
],
|
|
27
28
|
"scripts": {
|