Skip to content

Latest commit

 

History

History
139 lines (113 loc) · 37.8 KB

FEATURES.md

File metadata and controls

139 lines (113 loc) · 37.8 KB

Features and parity

All features are opt-in via controllers, use native buttons, support Enter/Space and ordinary Tab order, and expose pressed/disabled state or a polite numeric output. Defaults leave the host unchanged. Values persist once changed and return to defaults on Reset All. Effects persist when controls/panel disappear and are cleaned on provider removal. Widget portals are excluded. The engine restores prior inline properties and priorities instead of simply deleting them.

Controller / key Default; states and bounds Host behavior / edge cases
TextScaleController / fontScale 1.0; 1.0, 1.125, 1.25, 1.5, 2.0 (stepwise) Reflow-safe stepwise text enlargement without CSS transforms or compounding. Protects forms, labels, code, icons, widget, and exempt content.
FontSizeController / fontSize 100; 50–200%, step 10 or stepwise Scales computed font size and line height together. Supports optional stepScale / steps props; protects forms, labels, code blocks, icons, and widget UI.
LineHeightController / lineHeight 100; 50–200%, step 10 or stepwise presets Scales computed line height. Supports stepPresets (100%, 150%, 175%, 200% / 1.0x, 1.5x, 1.75x, 2.0x) and custom steps. Excludes tables, code blocks, controls, and widget UI.
LetterSpacingController / letterSpacing 0; 0–10px, step 1 Sets letter spacing on content elements. Protects cursive/Arabic/RTL scripts (disabled) and Indic/Sinhala/Tamil scripts (clamped <=1px). Excludes tables, code, and controls.
WordSpacingController / wordSpacing 0; 0–10px, step 1 Sets word spacing on content elements while protecting tables, code, controls, and widget UI.
ParagraphSpacingController / paragraphSpacing 0; 0–32px, step 4 Increases paragraph bottom margin (p, [role="paragraph"]) while protecting tables, code, and controls.
ContrastController / contrast 0; 0/1/2/3, light, dark, high, invert, reduced, named palettes Off, 1.25×, 1.5×, 2×; reduced=0.5×. Semantic light, dark, high contrast, and invert tokens protect images/video/SVG/charts and validation states. Bypasses overrides when OS forced-colors is active.
ContrastModeController / contrastMode off; off/light/dark/high/invert Semantic light, dark, high contrast, and media-safe invert modes. Preserves images, charts, and validation errors. Native forced-colors protection. See docs/CONTRAST.md.
SmartContrastController / smartContrast off; off/aa/aaa (or false/true) Opt-in measured smart contrast research prototype. Evaluates foreground relative luminance against computed backdrop without layout thrashing; blends semi-transparent ancestor layers; reports unsupported gradients/images; restores styles on reset. See docs/SMART_CONTRAST.md.
SaturationController / saturation 0; 0/1/2/3, "original"/"low"/"high"/"grayscale" Off, 0.2× (Low), 2× (High), and Grayscale modes. Composes with other filters. Features accessible chart/image advisory warnings and forced-colors bypass. See docs/SATURATION_AND_GRAYSCALE.md.
InvertColorsController / invertColors false; boolean Adds invert(1), includes content images.
GrayscaleController / grayscale false; boolean Adds grayscale(1) monochrome mode. Displays accessible visualization advisory warning and respects OS forced-colors. See docs/SATURATION_AND_GRAYSCALE.md.
LinkHighlightController / linkHighlight false; false/true/underline/palettes Non-color underline cues (2px thickness, 3px offset) and high-contrast palettes. Preserves disabled links and system LinkText in forced colors. See docs/LINKS_AND_FOCUS.md.
HighlightFocusController / highlightFocus false; boolean High-visibility dual-ring focus outline (3px blue + 5px white halo) with forced-colors Highlight support. Preserves disabled controls. See docs/LINKS_AND_FOCUS.md.
SkipToMainLink / findMainLandmark Dynamic helper / link Authentic skip-to-main landmark link. Only renders when a real <main> or [role="main"] exists. Transfers focus and scrolls into view. See docs/LINKS_AND_FOCUS.md.
TextAlignController / textAlign default; default/left/center/right/justify Scoped strictly to logical text blocks (p, headings, lists, blockquotes); excludes tables, form controls, and code. Justification displays an accessible WCAG SC 1.4.8 advisory warning.
FontFamilyController / fontFamily default; default/legible/dyslexia-option Applies clean system-ui or OpenDyslexic with Sinhala/Tamil fallbacks. Code blocks, icons, and SVGs are protected. See docs/FONTS.md.
HideImagesController / HideDecorativeImagesController / hideImages false; boolean | "all" | "decorative" HideImagesController (default mode="all") hides host img/picture/object/embed/decorative <svg> and CSS-based images (background-image, background shorthand, var(...), image-set(), ::before/::after, html/body, list-style-image, content: url()). HideDecorativeImagesController (and mode="decorative") restricts hiding to decorative images only. Protects widget UI, interactive controls, icon-only links, CAPTCHA, charts, maps, QR codes, math, and pure CSS gradients. See docs/DECORATIVE_IMAGES.md.
HideVideosController / hideVideos false; boolean Hides video and recognized YouTube/Vimeo embed URL patterns. Does not hide unrelated iframe documents, pause video or mute audio.
ReduceMotionController / reduceMotion false; boolean Scoped CSS animation and smooth-scroll suppression, tracked WAAPI animation pausing, and explicit media autoplay pause. Honors OS prefers-reduced-motion. See docs/REDUCE_MOTION.md.
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.
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.
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.
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.
PageNavigatorController / HeadingsNavigatorController / PageStructureController Action dialog; no persistent preference Scans real DOM headings (h1–h6) and named landmarks (banner, navigation, main, region, etc.). Safe scroll and focus with temporary tabindex cleanup, live mutation updates without loops, and search filtering. See docs/PAGE_NAVIGATOR.md.
ProfilesController / ProfileController / AccessibilityProfilesController activeProfile; ProfilePresetId / null Previews, applies, and reverts eight neutral presets (Motor, Blind, Color Blind, Dyslexia, Low Vision, Cognitive, Seizure, ADHD). Follows deterministic override model where user explicit choices survive reversal. Zero implicit audio/mic. See docs/PROFILES.md.
PresetsController / CustomPresetsController / SettingsImportExportController customPresets; CustomPreset[] Saves named user presets, 1-click apply/delete, and versioned JSON backup and transfer. Strict privacy exclusions discard private data, transcripts, and credentials. Saved presets library survives display reset. See docs/PRESETS.md.
Locales & i18n (en, si, si-LK, ta, ta-LK) LocaleStrings / locale prop Reviewed English, Sinhala, and Tamil locale packs with typography fallbacks and full RTL infrastructure. Automatic document.documentElement.lang resolution; host content is never translated. See docs/LOCALES.md.
ReadingModeController / readingMode false; boolean Non-destructive article extraction into an accessible overlay dialog. Preserves headings, links, images, and alt text while stripping forms, navigation, and sensitive fields. Supports Light/Sepia/Dark themes and zoom. See docs/READING_MODE.md.
KeyboardShortcutsController / shortcutsEnabled / customShortcuts false; boolean / Record<string, string> Discoverable shortcut cheat sheet, conflict-checked remapping, reserved browser protection (Ctrl+U, Ctrl+R), form suppression, and Link Explorer with uninformative text detection. See docs/KEYBOARD_SHORTCUTS.md.
ReadAloudController / readAloud / readAloudRate / readAloudPitch / readAloudVoice false; 1.0; 1.0; null User-initiated client-side text-to-speech read-aloud via Web Speech API (speechSynthesis). Sentence-level chunking, pause/resume/stop, voice selection, rate and pitch steppers, Escape dismissal, sensitive/form field exclusions, and zero network transmission. See docs/READ_ALOUD.md.
DictionaryController Action dialog; no persistent preference Accessible terminology dictionary and provider interface. Explicit user action lookup, 100% offline local static glossaries (English, Sinhala, Tamil), zero network transmission by default, truthful non-hallucinating responses, sensitive data rejection, and focus restoration. See docs/DICTIONARY.md.
VoiceNavigationController / voiceNavigation false; boolean User-initiated speech recognition navigation research prototype using native Web Speech API. Recognizes explicit commands (open, close, next/prev/first heading, scroll down/up/top/bottom, stop, help). Features 30s silence timeout, background tab auto-stop, zero audio storage, and full keyboard alternatives. See docs/VOICE_NAVIGATION.md.
FeatureMenu / menuConfig MenuCustomizationConfig; customizable Declarative per-site feature menu reordering, grouping, custom labels, suggested defaults, non-crashing safe diagnostics, and memoized stable rerenders. See docs/MENU_CUSTOMIZATION.md.
ResetController No feature state Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open.

Accessible control primitives and UI states

The library exports modular UI primitives conforming to WCAG 2.2 criteria:

Primitive Accessible Role & State Key Capabilities
ToggleControl role="switch", aria-checked Keyboard Space/Enter toggle, disabled/unavailable states, >=44px touch targets (>=48px in largeControls mode).
ChoiceControl role="radiogroup", role="radio", aria-checked Arrow key (Left/Right/Up/Down/Home/End) cycling, check indicators, multi-level/category grouping.
StepperControl role="group" with <output aria-live="polite"> Accessible increment/decrement buttons, boundary clamping, optional role="slider" range input.
FeatureCard role="group", aria-label Card container with title, icon, description, status badge, and alert states (idle, active, error, unavailable, permission-required).
SearchCount role="status", aria-live="polite" Live status announcement of matched and total features for search filtering.
EmptyState / ErrorState role="status" / role="alert" Clear messaging with action button for empty results and error recovery.
ProfilePreviewCard role="group" Previews affected settings for accessibility profiles (low-vision, dyslexia, etc.) and provides one-click reversal back to custom settings.

Original JavaScript and branch comparison

Reference: vanilla 47f44c5 (accessibility-menu.js, package 1.2.2); older React 7aef17c; newer baseline 6dfbd44. “Present” is source evidence, not proof of correctness. See baseline for defects.

Original behavior Older React Newer baseline Stabilized behavior
Invert + grayscale Exclusive contrast enum Independent but overwrite Independent, composable
Low 20% / high 200% saturation Exclusive modes 50% / 200%, overwrite Restore original 20% / 200%
Contrast 0.5 / 1.5 / 2 Replaced by named palettes 1.25 / 1.5 / 2 Preserve newer levels, add reduced 0.5 and older palettes
3 link palettes One highlighting toggle One toggle Default toggle plus all 3 original palettes
Font size 1.3/1.5/1.8rem on html Root scale 50–200% on html Fine-grained computed font scaling, including px fonts
Line height 1.5/1.8/2 on descendants Root inherited value Root percent Scale actual computed line height across descendants
Letter spacing .1/.2/.3rem em slider 0–10px root 0–10px descendant override
Left/center/right text alignment Includes initial Left is “off” Explicit default plus left/center/right/justify
Hide img / video with display:none Images only Images/videos plus some embeds Both; retain layout, restrict video embeds
Circle cursor enlarges on link hover Big cursor Static circle CSS cursor Large contrast pointer; decorative hover enlargement replaced
Reading mask clear center Guide only Dark strip obscures center Clear center restored
Quarter-width guide + triangle Guide Full-width line Full-width line; native cursor retained
Reset classes, sizes, counters Fixed state reset Generic reset, stale timer Generic reset, cancellation and effect restoration
Four user-selected placements, saved Draggable trigger Position prop, broken panel positioning Persisted free drag, four corners, Alt+arrow and click controls
Save on beforeunload, unguarded parse No localStorage persistence Debounced but shared timer Versioned/validated, per-owner debounce, pagehide/unmount flush

Widget placement is now a persisted preference with pointer dragging and non-drag alternatives. The initial position prop remains a fallback. Original cursor decoration remains deferred, not counted as visual parity. Original combinations enumerated CSS selectors; centralized composition avoids that unmaintainable combinatorial model. Original click-only div controls are replaced with native named buttons.

Verification mapping

tests/features.test.tsx: stepper bounds, palettes, all alignment states, boolean effects, combined filters, native host restoration and dynamic routes. tests/plugin.test.tsx: custom lifecycle, restoration, invalid data, focus, Strict Mode, SSR, hydration, singleton enforcement. tests/storage.test.ts: deterministic timers, errors and schema envelopes. tests/browser/widget.spec.ts: actual compiled CSS, packed consumers, visibility, pointer interaction, geometry, keyboard and axe. See project status for executed results and manual gaps.

Development-Only Integration Diagnostics & Test Harness (A11Y-405)

The integration diagnostics suite (runDiagnostics, DiagnosticsHarness, useDiagnostics) performs non-invasive environment, DOM, and styling checks during development:

  • Provider & Widget Placement: Diagnoses multiple providers and identifies ancestor containing-block traps (filter, transform, perspective).
  • Storage Boundaries: Tests localStorage / sessionStorage accessibility, quotas, and sandbox restrictions with graceful in-memory fallback.
  • CSP & Style Injection: Tests dynamic <style> injection and CSS custom property support against restrictive style-src.
  • Host CSS Conflicts: Detects extreme host z-index >= 2,147,483,000 and root scroll locks (overflow: hidden on both html and body).
  • DOM & Landmark Structure: Scans for <main> landmarks, <h1> titles, skipped heading levels, and unlabelled content <img> tags (privacy-safe, no sensitive URLs or PII).
  • Boundaries: Flags embedded <iframe> elements (cross-origin styling boundaries) and custom elements with ShadowRoot.
  • Zero Compliance Claims: All reports carry an explicit disclaimer stating that automated diagnostics do not constitute official WCAG certification or replace manual audits.

Optional Privacy-Safe Feature Event Callbacks (A11Y-406)

The optional lifecycle callback (onFeatureEvent on <AccessibilityPlugin>) provides local, in-memory event notifications for host application telemetry:

  • Strictly Opt-In: Disabled by default; zero events or network requests are emitted unless an explicit listener callback is supplied.
  • Reviewed Payloads: Emits coarse event types (feature-change, feature-reset, panel-toggle, placement-change, profile-apply, preset-apply) with scalar values and canonical feature IDs.
  • Strict Privacy Exclusions: Never includes page text, user text selections, form inputs, emails, user IDs, cookies, device fingerprints, or Web Speech transcripts/audio recordings.
  • Sanitized and Frozen: All payloads are validated against an allowlist and deep-frozen (Object.freeze).
  • Resilient: Exceptions thrown in consumer listeners are safely caught and silenced, ensuring application functionality is never interrupted.

Smart Contrast Research Prototype (A11Y-407)

The Smart Contrast Research Prototype (SmartContrastController, evaluateSmartContrast, applySmartContrast) dynamically evaluates and enhances text contrast ratios using WCAG relative luminance algorithms and alpha compositing:

  • Mathematical Luminance & Compositing: Evaluates background luminance by traversing parent hierarchies and alpha-compositing semi-transparent backgrounds (compositeRgba) against the viewport root.
  • 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).
  • Graceful Unsupported Handling: Transparently flags and skips unsupported complex elements (background images, CSS gradients, complex filters, canvas/video backdrops) while providing live diagnostic statistics.
  • 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.
  • Zero WCAG Overclaim: Prominently labeled with a Prototype badge and disclaimer (SMART_CONTRAST_DISCLAIMER) stating mathematical calculations do not certify official WCAG compliance.

Voice Navigation Research Prototype (A11Y-408)

The Voice Navigation Research Prototype (VoiceNavigationController, createVoiceNavigationSession) provides user-initiated speech control for page navigation:

  • Local Speech Recognition: Leverages client platform Web Speech Recognition API with zero external network transmission.
  • Strict Privacy Guarantees: Zero recording or audio persistence in localStorage, sessionStorage, or cookies; interim/final transcripts are purely transient in component memory.
  • Inactivity Watchdog: Automatically shuts down listening after 30 seconds of silence to prevent open background microphones.
  • Background Tab Protection: Automatically stops speech recognition when document.hidden becomes true.
  • Accessible Keyboard Alternatives: Full set of native buttons for heading navigation and scrolling; 100% operational in unsupported browsers or upon permission denial.
  • Reduced Motion Respect: Automatically disables smooth scrolling in favor of instant jumps when reduced motion preferences are detected.

Host-Content Translation Adapter Architecture (A11Y-409)

The Host-Content Translation Adapter Architecture (TranslationController, translateHostContent) provides a privacy-first, decoupled bridge for translating arbitrary host application text:

  • Decoupled from Widget Localization: Clear separation between bundled static widget strings (src/core/i18n/) and host content translation.
  • Provider Interface Boundary: Pluggable TranslationAdapter interface specifying data retention, residency, and privacy policies.
  • Explicit User Consent: Strictly user-initiated; requires explicit acknowledgment via consent modal before transmitting host document text.
  • Strict Sensitive Content Exclusion: Automatically detects and ignores form passwords, credit card/CVC fields, personal email/phone inputs, technical code blocks (<code>, <pre>), media boundaries (<iframe>, <svg>), opt-out attributes ([translate="no"]), hidden nodes, and the widget itself.
  • Cross-Origin & iframe Safeguard: Strictly excludes all <iframe> elements to protect Same-Origin Policy (SOP) boundaries.
  • XSS & DOM Injection Prevention: Translated text is strictly assigned via Text.textContent, never innerHTML.
  • Clean Synchronous Restoration: Synchronous restore() callback resets modified text nodes back to original host strings immediately.
  • Offline Mock Translation Adapter: createOfflineMockTranslationAdapter operates locally with zero network calls for testing and development.