accessibility-plugin-react 2.16.0 → 2.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,128 @@
1
+ # Non-Destructive Reading Mode (`ReadingModeController`)
2
+
3
+ The **Reading Mode** feature (`ReadingModeController`, key `readingMode`) provides a distraction-free, high-readability article view that extracts long-form text and media into an accessible reading modal without rewriting or unmounting the host application's React DOM tree.
4
+
5
+ ---
6
+
7
+ ## Architecture and Core Principles
8
+
9
+ ### 1. Strictly Non-Destructive Extraction
10
+
11
+ Traditional browser reader modes or third-party bookmarklets often replace or mutate the underlying document body, destroying client-side React component trees, losing form input state, breaking single-page application (SPA) routing, and detaching event listeners.
12
+
13
+ The `accessibility-plugin-react` implementation is **100% non-destructive**:
14
+
15
+ - The article extractor clones the candidate content element (`node.cloneNode(true)`) in memory.
16
+ - The original host DOM tree is **never rewritten, detached, or mutated**.
17
+ - Interactive host elements (such as counters, search fields, or form inputs) retain their exact state, event listeners, and focus history before, during, and after a reading session.
18
+
19
+ ### 2. Client-Side Confidentiality (Zero External Network Requests)
20
+
21
+ - Extraction, scoring, sanitization, and rendering execute purely in memory in the user's browser.
22
+ - **No external APIs, cloud extractors, or third-party web services** are contacted.
23
+ - Verified in automated test suites: zero calls to `fetch`, `XMLHttpRequest`, or `navigator.sendBeacon`.
24
+
25
+ ### 3. Sensitive Field and Non-Article Stripping
26
+
27
+ Even when articles contain nested widgets or forms, the extractor strictly sanitizes all disallowed and sensitive markup:
28
+
29
+ - **Sensitive inputs**: Password fields (`input[type="password"]`), credit card inputs (`[autocomplete*="cc-"]`), CSRF/hidden tokens, and sensitive data attributes (`[data-sensitive]`) are stripped completely.
30
+ - **Forms and interactive inputs**: `<form>`, `<input>`, `<select>`, `<textarea>`, and `<button>` elements are removed to prevent state ambiguity.
31
+ - **Boilerplate and navigation**: `<nav>`, `<header>`, `<footer>`, `<aside>`, modals/dialogs, cookie banners, advertisements, and social share widgets are filtered out.
32
+ - **Dangerous code and handlers**: `<script>`, `<iframe>`, `<object>`, `<embed>`, inline event handlers (`onclick`, etc.), and unsafe URL protocols (`javascript:`, `vbscript:`) are sanitized.
33
+
34
+ ### 4. Preservation of Semantic Structure
35
+
36
+ The extractor preserves meaningful article semantics:
37
+
38
+ - **Headings**: `h1` through `h6` retaining clear hierarchy.
39
+ - **Typography & Flow**: `p`, `blockquote`, `pre`, `code`, `time`, and emphasis (`strong`, `em`, `mark`).
40
+ - **Lists & Tables**: `ul`, `ol`, `li`, `table`, `thead`, `tbody`, `tr`, `th`, `td`.
41
+ - **Hyperlinks**: `a[href]` with safe URLs (`https://`, relative paths, anchor fragments), decorated with `target="_blank"` and `rel="noopener noreferrer"`.
42
+ - **Images and Media**: `img[src]` preserving `alt` text and dimensions, together with `<figure>` and `<figcaption>` captions.
43
+
44
+ ### 5. Honest Fallback and Failure Recovery
45
+
46
+ If a page lacks substantive readable content (e.g. an authentication screen, an empty dashboard, or a navigation-only hub):
47
+
48
+ - Extraction gracefully fails without throwing an unhandled exception or trapping the user in a blank view.
49
+ - The toggle state automatically reverts to `false`.
50
+ - A polite status announcement is communicated to assistive technology:
51
+ - English: _"No readable article content found on this page."_
52
+ - Sinhala: _"මෙම පිටුවෙහි කියවිය හැකි ලිපි අන්තර්ගතයක් හමු නොවීය."_
53
+ - Tamil: _"இப்பக்கத்தில் படிக்கக்கூடிய கட்டுரை உள்ளடக்கம் எதுவும் இல்லை."_
54
+ - Focus safely returns to the triggering control.
55
+
56
+ ---
57
+
58
+ ## User Experience and Controls
59
+
60
+ When reading mode is opened, it renders an accessible overlay dialog (`role="dialog"`, `aria-modal="true"`):
61
+
62
+ 1. **Toolbar Header**:
63
+ - **Article Meta**: Displays word count and estimated reading time (standard 200 words-per-minute baseline).
64
+ - **Theme Switcher**: Quick toggle between **Light**, **Sepia** (reduced blue light), and **Dark** modes.
65
+ - **Text Scaling**: Incremental zoom steppers (`A-` and `A+`) allowing text scaling between 90% and 160%.
66
+ - **Close Button**: Accessible `×` button with minimum 44×44px touch targets.
67
+ 2. **Focus Management & Keyboard Accessibility**:
68
+ - Focus is automatically placed inside the dialog when opened.
69
+ - Focus is trapped within interactive controls inside the dialog during the reading session (`Tab` / `Shift+Tab`).
70
+ - Pressing `Escape` immediately dismisses the reader view and restores focus to the invoking launcher/toggle button.
71
+ - Footer contains an explicit "Close Reading Mode" button for touch and keyboard users.
72
+
73
+ ---
74
+
75
+ ## Component Usage
76
+
77
+ ### Basic Compound Integration
78
+
79
+ ```tsx
80
+ import {
81
+ AccessibilityPlugin,
82
+ AccessibilityButton,
83
+ AccessibilityList,
84
+ ReadingModeController,
85
+ } from "accessibility-plugin-react";
86
+ import "accessibility-plugin-react/styles.css";
87
+
88
+ export function App() {
89
+ return (
90
+ <AccessibilityPlugin>
91
+ <AccessibilityButton />
92
+ <AccessibilityList>
93
+ <ReadingModeController />
94
+ </AccessibilityList>
95
+ </AccessibilityPlugin>
96
+ );
97
+ }
98
+ ```
99
+
100
+ ### Standalone Extractor Utility
101
+
102
+ For headless or custom reader implementations, the core extractor function is exported directly:
103
+
104
+ ```ts
105
+ import { extractArticleContent } from "accessibility-plugin-react";
106
+
107
+ const article = extractArticleContent(document.body);
108
+ if (article) {
109
+ console.log(`Title: ${article.title}`);
110
+ console.log(
111
+ `Words: ${article.wordCount} (~${article.readingTimeMinutes} min)`,
112
+ );
113
+ console.log(`Sanitized HTML: ${article.html}`);
114
+ } else {
115
+ console.log("No readable article content found on this page.");
116
+ }
117
+ ```
118
+
119
+ ---
120
+
121
+ ## Technical Specifications & Verification
122
+
123
+ - **Feature Key**: `readingMode` (Boolean, default: `false`).
124
+ - **Storage Compatibility**: Fully integrated with preference storage modes (`local`, `session`, `none`) and cleanly reset via `resetAll()`.
125
+ - **Test Matrix**:
126
+ - `tests/readingMode.test.ts`: Candidate scoring, sensitive field exclusion, protocol sanitization, image alt preservation, and offline execution.
127
+ - `tests/readingModeWidget.test.tsx`: Modal lifecycle, theme switching, Escape key dismissal, host React state persistence across open/close, and Sinhala/Tamil localization.
128
+ - `tests/browser/widget.spec.ts`: Playwright browser smoke test for live extraction, DOM isolation, theme switching, and host button interactivity.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "accessibility-plugin-react",
3
- "version": "2.16.0",
3
+ "version": "2.18.0",
4
4
  "description": "A composable React display-preference widget with a clean light design, persistent settings and movable accessible controls.",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",