accessibility-plugin-react 2.3.0 → 2.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -3
- package/docs/API.md +19 -7
- package/docs/BUILD_AND_RELEASE_PLAN.md +9 -9
- package/docs/CSP.md +185 -0
- package/docs/DEVELOPMENT.md +30 -3
- package/docs/FEATURES.md +14 -0
- package/docs/INSTALLATION.md +7 -1
- package/package.json +3 -1
package/README.md
CHANGED
|
@@ -4,8 +4,7 @@ Composable React controls for display preferences and reading assistance. Choose
|
|
|
4
4
|
the controls in JSX, keep the widget outside your application layout, and let
|
|
5
5
|
the provider own state, persistence, effects, focus behavior, and cleanup.
|
|
6
6
|
|
|
7
|
-
The `2.0
|
|
8
|
-
import while retaining the standalone stylesheet export for explicit pipelines.
|
|
7
|
+
The `2.3.0` minor release introduces modular accessible control primitives (`FeatureCard`, `ToggleControl`, `ChoiceControl`, `StepperControl`), state UI (`SearchCount`, `EmptyState`, `ErrorState`), profile previews (`ProfilePreviewCard`), locale and oversized control modes (`largeControls`), and automated releases across npm, GitHub Releases, and GitHub Packages.
|
|
9
8
|
It supports React 18.3.1 and React 19.x, ships ESM, CommonJS, TypeScript declarations,
|
|
10
9
|
and scoped plain CSS, and has no runtime dependency other than React and React DOM.
|
|
11
10
|
|
|
@@ -18,10 +17,18 @@ and scoped plain CSS, and has no runtime dependency other than React and React D
|
|
|
18
17
|
|
|
19
18
|
## Installation
|
|
20
19
|
|
|
20
|
+
### From npm (recommended)
|
|
21
|
+
|
|
21
22
|
```sh
|
|
22
23
|
npm install accessibility-plugin-react
|
|
23
24
|
```
|
|
24
25
|
|
|
26
|
+
### From GitHub Packages
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
npm install @prabothcharith/accessibility-plugin-react --registry=https://npm.pkg.github.com
|
|
30
|
+
```
|
|
31
|
+
|
|
25
32
|
React and React DOM are peer dependencies and must use the same major/minor
|
|
26
33
|
line. The package requires Node.js 22.13 or newer for development and builds.
|
|
27
34
|
The widget itself does not require an API key, backend, environment variable,
|
|
@@ -104,6 +111,17 @@ and grayscale are applied in a deterministic order. Defaults leave host styles
|
|
|
104
111
|
unchanged, and the provider restores host inline values and priorities when an
|
|
105
112
|
effect is disabled or the provider is removed.
|
|
106
113
|
|
|
114
|
+
## Control primitives and profiles
|
|
115
|
+
|
|
116
|
+
Build custom accessible panels or custom features with modular primitives that include ARIA semantics, keyboard navigation, and Clean light styling:
|
|
117
|
+
|
|
118
|
+
- **`FeatureCard`**: Accessible container with header, icon, description, status badge, and alert states (`idle`, `active`, `error`, `unavailable`, `permission-required`).
|
|
119
|
+
- **`ToggleControl`**: Native switch button with `role="switch"`, `aria-checked`, and >=44px touch targets.
|
|
120
|
+
- **`ChoiceControl`**: Segmented or grouped choices with `role="radiogroup"`, Arrow key navigation (Left/Right/Up/Down/Home/End), and visual check indicators.
|
|
121
|
+
- **`StepperControl`**: Bounded decrement/increment buttons, `<output aria-live="polite">`, and optional range slider.
|
|
122
|
+
- **`SearchCount` & `EmptyState`**: Polite live announcements for feature filtering and search zero-results states.
|
|
123
|
+
- **`ProfilePreviewCard`**: Previews affected accessibility profile settings (e.g. low-vision, dyslexia, cognitive) and provides one-click reversal back to custom settings.
|
|
124
|
+
|
|
107
125
|
## Custom features
|
|
108
126
|
|
|
109
127
|
Use the two-argument hook for simple state, or provide validation and a
|
|
@@ -229,7 +247,7 @@ export function AccessibilitySettings() {
|
|
|
229
247
|
```
|
|
230
248
|
|
|
231
249
|
See [installation and Next.js](docs/INSTALLATION.md) for App Router and Pages
|
|
232
|
-
Router examples.
|
|
250
|
+
Router examples, runnable code in [`examples/next-app/`](examples/next-app/), and [strict CSP guidance](docs/CSP.md).
|
|
233
251
|
|
|
234
252
|
## API and limitations
|
|
235
253
|
|
|
@@ -256,6 +274,7 @@ See [troubleshooting](docs/TROUBLESHOOTING.md) before filing an issue.
|
|
|
256
274
|
- [API reference](docs/API.md)
|
|
257
275
|
- [Feature behavior and bounds](docs/FEATURES.md)
|
|
258
276
|
- [Installation and Next.js](docs/INSTALLATION.md)
|
|
277
|
+
- [Content Security Policy (CSP) guidance](docs/CSP.md)
|
|
259
278
|
- [Custom features](docs/CUSTOM_FEATURES.md)
|
|
260
279
|
- [Migration from v1 and development baselines](docs/MIGRATION.md)
|
|
261
280
|
- [Architecture and lifecycle decisions](docs/ARCHITECTURE.md)
|
package/docs/API.md
CHANGED
|
@@ -4,12 +4,18 @@ All exports are named from `accessibility-plugin-react`. JavaScript consumers re
|
|
|
4
4
|
|
|
5
5
|
## Components
|
|
6
6
|
|
|
7
|
-
| Component | Props
|
|
8
|
-
| --------------------------------------------- |
|
|
9
|
-
| AccessibilityPlugin | `children: ReactNode` required; `position?: 'left' \| 'right' \| 'top' \| 'bottom'` default right; `persistenceKey?: string` default `react-accessibility-plugin:state`; `persist?: boolean` default true
|
|
10
|
-
| AccessibilityButton | `draggable?: boolean` default true (pointer/Alt+arrow movement); `icon?: ReactNode` default inline accessibility SVG; `title?: string` accessible name, default Accessibility; `description?: string` supplementary accessible description; `className?: string`; `style?: CSSProperties`
|
|
11
|
-
| AccessibilityList | `footer?: ReactNode` extra fixed actions; `children: ReactNode` required; `title?: string` visible heading and region name, default Accessibility settings; `description?: string` default Adjust your reading experience
|
|
12
|
-
|
|
|
7
|
+
| Component | Props |
|
|
8
|
+
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
9
|
+
| AccessibilityPlugin | `children: ReactNode` required; `position?: 'left' \| 'right' \| 'top' \| 'bottom'` default right; `persistenceKey?: string` default `react-accessibility-plugin:state`; `persist?: boolean` default true; `storage?: 'local' \| 'session' \| 'none'` default local; `locale?: string`; `statementUrl?: string`; `largeControls?: boolean` default false |
|
|
10
|
+
| AccessibilityButton | `draggable?: boolean` default true (pointer/Alt+arrow movement); `icon?: ReactNode` default inline accessibility SVG; `title?: string` accessible name, default Accessibility; `description?: string` supplementary accessible description; `className?: string`; `style?: CSSProperties`; `largeControls?: boolean` |
|
|
11
|
+
| AccessibilityList | `footer?: ReactNode` extra fixed actions; `children: ReactNode` required; `title?: string` visible heading and region name, default Accessibility settings; `description?: string` default Adjust your reading experience; `closeLabel?: string` default Close; `statementUrl?: string`; `largeControls?: boolean`; `locale?: string`; `className?: string`; `style?: CSSProperties` |
|
|
12
|
+
| FeatureCard | `title: ReactNode` required; `children: ReactNode` required; `featureKey?: string`; `icon?: ReactNode`; `description?: ReactNode`; `statusBadge?: string`; `status?: 'idle' \| 'active' \| 'error' \| 'unavailable' \| 'permission-required'`; `errorMessage?: string`; `unavailableMessage?: string`; `permissionMessage?: string`; `onRequestPermission?: () => void`; `largeControls?: boolean` |
|
|
13
|
+
| ToggleControl | `label: ReactNode` required; `checked: boolean` required; `onChange: (checked: boolean) => void` required; `disabled?: boolean`; `unavailable?: boolean`; `unavailableReason?: string`; `largeControls?: boolean` |
|
|
14
|
+
| ChoiceControl | `label: string` required; `value: T` required; `options?: ChoiceOption<T>[]`; `groups?: ChoiceGroup<T>[]`; `onChange: (value: T) => void` required; `disabled?: boolean`; `largeControls?: boolean` |
|
|
15
|
+
| StepperControl | `label: string` required; `value: number` required; `min: number`; `max: number`; `step: number`; `unit?: string` default '%'; `showSlider?: boolean`; `formatValue?: (val: number) => string`; `onChange: (value: number) => void` required; `disabled?: boolean`; `largeControls?: boolean` |
|
|
16
|
+
| ProfilePreviewCard | `profile: ProfileDefinition` required; `isActive: boolean` required; `onApply: (profile: ProfileDefinition) => void` required; `onRevert: () => void` required; `largeControls?: boolean` |
|
|
17
|
+
| SearchCount / EmptyState / ErrorState | Standalone accessible status and announcement primitives for search counts, zero-results fallbacks, and error recovery banners. |
|
|
18
|
+
| All fifteen controllers listed in FEATURES.md | No props. Pick/omit in JSX. For custom labels or behavior, compose a control with useAccessibility or the modular control primitives. |
|
|
13
19
|
|
|
14
20
|
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.
|
|
15
21
|
|
|
@@ -37,7 +43,13 @@ Definitions/defaults are immutable for the provider lifetime; the first register
|
|
|
37
43
|
|
|
38
44
|
`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.
|
|
39
45
|
|
|
40
|
-
Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions<T>`, `FeatureRegistration`.
|
|
46
|
+
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`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`.
|
|
47
|
+
|
|
48
|
+
Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`.
|
|
49
|
+
|
|
50
|
+
Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
|
|
51
|
+
|
|
52
|
+
Exported localization utilities: `enLocale`, `registerLocale`, `resolveLocaleStrings`, `isRtlLocale`.
|
|
41
53
|
|
|
42
54
|
## Styling and labels
|
|
43
55
|
|
|
@@ -70,15 +70,15 @@ completed. Closing a child issue does not replace the milestone exit review.
|
|
|
70
70
|
|
|
71
71
|
### M1 — Safe core and accessible widget
|
|
72
72
|
|
|
73
|
-
- [
|
|
74
|
-
- [
|
|
75
|
-
- [
|
|
76
|
-
- [
|
|
77
|
-
- [
|
|
78
|
-
- [
|
|
79
|
-
- [
|
|
80
|
-
- [
|
|
81
|
-
- [
|
|
73
|
+
- [x] [A11Y-101 — Typed preferences registry and state reducer #32](https://github.com/prabothcharith/accessibility-react/issues/32) — Implement typed preference definitions, validation, defaults, stable feature IDs and reducer logic for effective settings and profile overrides.
|
|
74
|
+
- [x] [A11Y-102 — Scoped effect manager and cleanup lifecycle #33](https://github.com/prabothcharith/accessibility-react/issues/33) — Implement provider-owned idempotent effect apply/dispose lifecycle with scoped styles, listener cleanup, widget exclusion and Strict Mode safety.
|
|
75
|
+
- [x] [A11Y-103 — Versioned storage, reset, migration and no-storage fallback #34](https://github.com/prabothcharith/accessibility-react/issues/34) — Implement versioned `none`/session/local storage, migrations, validation, reset of owned keys, blocked-storage handling and temporary no-remember mode.
|
|
76
|
+
- [x] [A11Y-104 — Accessible launcher and non-modal widget panel #35](https://github.com/prabothcharith/accessibility-react/issues/35) — Build the keyboard and screen-reader accessible non-modal launcher/panel with visible focus, Escape, focus restoration, responsive layout and stable scrolling.
|
|
77
|
+
- [x] [A11Y-105 — Feature cards and state/value UI #36](https://github.com/prabothcharith/accessibility-react/issues/36) — Build reusable native feature controls for toggles, choices, sliders, search, values, statuses, errors, unsupported states and profile previews.
|
|
78
|
+
- [x] [A11Y-106 — Position, oversized controls, statement link and help #37](https://github.com/prabothcharith/accessibility-react/issues/37) — Implement position and non-drag movement, oversized controls, safe-area actions, conditional statement link and help while reconciling existing positioning work.
|
|
79
|
+
- [x] [A11Y-107 — Base locale infrastructure and English strings #38](https://github.com/prabothcharith/accessibility-react/issues/38) — Add typed English locale strings, configured/html-language fallback, BCP 47 and RTL handling, announcements and safe missing-key behavior.
|
|
80
|
+
- [x] [A11Y-108 — Vite and Next.js App Router consumer integrations #39](https://github.com/prabothcharith/accessibility-react/issues/39) — Provide Vite and Next.js App Router consumers and verify hydration, portals, React peer versions, CSS, declarations, themes and CSP guidance.
|
|
81
|
+
- [x] [A11Y-109 — CI for typecheck, lint, unit, axe and browser smoke #40](https://github.com/prabothcharith/accessibility-react/issues/40) — Establish CI for typecheck, lint, unit/integration, relevant axe checks, packed browser smoke and supported browser jobs without publication credentials.
|
|
82
82
|
|
|
83
83
|
### M2 — Stable visual and typographic features
|
|
84
84
|
|
package/docs/CSP.md
ADDED
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
# Content Security Policy (CSP) Guidance
|
|
2
|
+
|
|
3
|
+
This guide explains how `accessibility-plugin-react` operates under Content Security Policy (CSP), the specific directives involved, and copy-pasteable recipes for strict environments in Next.js, Vite, and static deployments.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. How the Library Works Under CSP
|
|
8
|
+
|
|
9
|
+
`accessibility-plugin-react` is designed to be lightweight, modular, and dependency-free. However, because it dynamically adapts host pages according to user accessibility preferences, several CSP directives are relevant:
|
|
10
|
+
|
|
11
|
+
### A. Scoped Stylesheet Injection (`style-src`)
|
|
12
|
+
|
|
13
|
+
- **Default behavior:** Importing `accessibility-plugin-react` automatically injects its scoped stylesheet (`.arap-root { ... }`) into `document.head` via a runtime `<style>` element.
|
|
14
|
+
- **Strict CSP (`style-src 'self'` without `'unsafe-inline'`):** If your CSP policy disallows inline `<style>` tags, you should import the standalone stylesheet directly in your build or application entry point instead of relying on runtime injection:
|
|
15
|
+
```tsx
|
|
16
|
+
// app/layout.tsx (Next.js) or main.tsx (Vite)
|
|
17
|
+
import "accessibility-plugin-react/style.css";
|
|
18
|
+
```
|
|
19
|
+
Because `style.css` is processed by your bundler (webpack, Vite, Turbopack) as a static asset, it is served from `'self'` and requires no inline script or style permissions.
|
|
20
|
+
|
|
21
|
+
### B. Element Style Mutations (`style-src-attr`)
|
|
22
|
+
|
|
23
|
+
- **How effects are applied:** The scoped effect manager applies display preferences (such as font scaling, line height, letter spacing, contrast, saturation, and color filters) directly to DOM elements via the CSSOM (e.g., `element.style.fontSize = "120%"`).
|
|
24
|
+
- **CSP Level 3 considerations:** In modern browsers enforcing CSP Level 3, mutations to an element's `.style` attribute are governed by `style-src-attr`.
|
|
25
|
+
- **Recommended directive:**
|
|
26
|
+
```text
|
|
27
|
+
style-src-attr 'unsafe-inline';
|
|
28
|
+
```
|
|
29
|
+
Note that `style-src-attr 'unsafe-inline'` does not allow arbitrary `<style>` tags; it only permits direct style property mutations on DOM elements.
|
|
30
|
+
|
|
31
|
+
### C. Big Cursor and High-Contrast Overlays (`img-src`)
|
|
32
|
+
|
|
33
|
+
- **How cursor enlargement works:** The `BigCursorController` dynamically generates an SVG data URI cursor (`data:image/svg+xml,...`) to provide high-visibility, high-contrast pointer cursors without requiring external network requests.
|
|
34
|
+
- **Recommended directive:**
|
|
35
|
+
```text
|
|
36
|
+
img-src 'self' data:;
|
|
37
|
+
```
|
|
38
|
+
If `data:` is omitted from `img-src`, the browser will fall back to native system cursors.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 2. Next.js App Router Strict CSP Recipe
|
|
43
|
+
|
|
44
|
+
In Next.js App Router, you can set CSP headers in `next.config.mjs` or dynamically in `middleware.ts` with nonces.
|
|
45
|
+
|
|
46
|
+
### Option 1: Static Headers via `next.config.mjs` (Recommended)
|
|
47
|
+
|
|
48
|
+
```javascript
|
|
49
|
+
// next.config.mjs
|
|
50
|
+
/** @type {import('next').NextConfig} */
|
|
51
|
+
const cspHeader = `
|
|
52
|
+
default-src 'self';
|
|
53
|
+
script-src 'self' 'unsafe-eval' 'unsafe-inline';
|
|
54
|
+
style-src 'self' 'unsafe-inline';
|
|
55
|
+
style-src-attr 'unsafe-inline';
|
|
56
|
+
img-src 'self' data:;
|
|
57
|
+
font-src 'self';
|
|
58
|
+
object-src 'none';
|
|
59
|
+
base-uri 'self';
|
|
60
|
+
form-action 'self';
|
|
61
|
+
frame-ancestors 'none';
|
|
62
|
+
`
|
|
63
|
+
.replace(/\s{2,}/g, " ")
|
|
64
|
+
.trim();
|
|
65
|
+
|
|
66
|
+
const nextConfig = {
|
|
67
|
+
reactStrictMode: true,
|
|
68
|
+
async headers() {
|
|
69
|
+
return [
|
|
70
|
+
{
|
|
71
|
+
source: "/(.*)",
|
|
72
|
+
headers: [
|
|
73
|
+
{
|
|
74
|
+
key: "Content-Security-Policy",
|
|
75
|
+
value: cspHeader,
|
|
76
|
+
},
|
|
77
|
+
],
|
|
78
|
+
},
|
|
79
|
+
];
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
export default nextConfig;
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
When using `'self'` without `'unsafe-inline'` in `style-src`, ensure you import the stylesheet in `app/layout.tsx`:
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
// app/layout.tsx
|
|
90
|
+
import "accessibility-plugin-react/style.css";
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Option 2: Dynamic Nonce via `middleware.ts`
|
|
94
|
+
|
|
95
|
+
If your organization requires cryptographic nonces for script and style execution:
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
// middleware.ts
|
|
99
|
+
import { NextRequest, NextResponse } from "next/server";
|
|
100
|
+
|
|
101
|
+
export function middleware(request: NextRequest) {
|
|
102
|
+
const nonce = Buffer.from(crypto.randomUUID()).toString("base64");
|
|
103
|
+
const cspHeader = `
|
|
104
|
+
default-src 'self';
|
|
105
|
+
script-src 'self' 'nonce-${nonce}' 'strict-dynamic';
|
|
106
|
+
style-src 'self' 'nonce-${nonce}';
|
|
107
|
+
style-src-attr 'unsafe-inline';
|
|
108
|
+
img-src 'self' data:;
|
|
109
|
+
font-src 'self';
|
|
110
|
+
base-uri 'self';
|
|
111
|
+
form-action 'self';
|
|
112
|
+
`
|
|
113
|
+
.replace(/\s{2,}/g, " ")
|
|
114
|
+
.trim();
|
|
115
|
+
|
|
116
|
+
const requestHeaders = new Headers(request.headers);
|
|
117
|
+
requestHeaders.set("x-nonce", nonce);
|
|
118
|
+
requestHeaders.set("Content-Security-Policy", cspHeader);
|
|
119
|
+
|
|
120
|
+
const response = NextResponse.next({
|
|
121
|
+
request: {
|
|
122
|
+
headers: requestHeaders,
|
|
123
|
+
},
|
|
124
|
+
});
|
|
125
|
+
response.headers.set("Content-Security-Policy", cspHeader);
|
|
126
|
+
return response;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
export const config = {
|
|
130
|
+
matcher: [
|
|
131
|
+
{
|
|
132
|
+
source: "/((?!api|_next/static|_next/image|favicon.ico).*)",
|
|
133
|
+
missing: [
|
|
134
|
+
{ type: "header", key: "next-router-prefetch" },
|
|
135
|
+
{ type: "header", key: "purpose", value: "prefetch" },
|
|
136
|
+
],
|
|
137
|
+
},
|
|
138
|
+
],
|
|
139
|
+
};
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 3. Vite / Single Page App Strict CSP Recipe
|
|
145
|
+
|
|
146
|
+
For Vite applications, configure CSP headers either through your production web server (nginx, Apache, Caddy, Cloudflare) or directly in `index.html`:
|
|
147
|
+
|
|
148
|
+
```html
|
|
149
|
+
<!-- index.html -->
|
|
150
|
+
<!doctype html>
|
|
151
|
+
<html lang="en">
|
|
152
|
+
<head>
|
|
153
|
+
<meta charset="UTF-8" />
|
|
154
|
+
<meta
|
|
155
|
+
http-equiv="Content-Security-Policy"
|
|
156
|
+
content="
|
|
157
|
+
default-src 'self';
|
|
158
|
+
script-src 'self';
|
|
159
|
+
style-src 'self' 'unsafe-inline';
|
|
160
|
+
style-src-attr 'unsafe-inline';
|
|
161
|
+
img-src 'self' data:;
|
|
162
|
+
font-src 'self';
|
|
163
|
+
"
|
|
164
|
+
/>
|
|
165
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
166
|
+
<title>Accessible App</title>
|
|
167
|
+
</head>
|
|
168
|
+
<body>
|
|
169
|
+
<div id="root"></div>
|
|
170
|
+
<script type="module" src="/src/main.tsx"></script>
|
|
171
|
+
</body>
|
|
172
|
+
</html>
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## 4. Verification Checklist
|
|
178
|
+
|
|
179
|
+
| Requirement | Directive | Why It Is Needed |
|
|
180
|
+
| :---------------------------- | :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
|
|
181
|
+
| **Widget UI Styles** | `style-src 'self'` (with static `style.css` import) | Renders the Clean light widget panel, trigger, and control cards |
|
|
182
|
+
| **Dynamic Host Effects** | `style-src-attr 'unsafe-inline'` | Applies runtime font-size, line-height, and filter adjustments to host elements |
|
|
183
|
+
| **Big High-Contrast Cursor** | `img-src 'self' data:` | Allows SVG data URI pointer rendering |
|
|
184
|
+
| **No External Font Requests** | `font-src 'self'` | The plugin does not load external web fonts; all font-legibility features use local and system fallbacks |
|
|
185
|
+
| **No Network Calls** | No special `connect-src` | All preferences, state persistence, and effects operate 100% locally on the client |
|
package/docs/DEVELOPMENT.md
CHANGED
|
@@ -18,9 +18,25 @@ npm run test:browser
|
|
|
18
18
|
|
|
19
19
|
For a PR under review, check out its head branch instead and record the tested commit. Main contains the merged stabilization and Clean light foundation; PR #17 adds movement and fixed actions.
|
|
20
20
|
|
|
21
|
-
`validate` runs typecheck, lint, unit tests and JS/declaration/CSS build. `test:consumers` builds, packs and installs the archive in `.consumers/react18`, `.consumers/react19` and `.consumers/next`, checks ESM/CJS and declarations/SSR, and produces application production builds. Consumers use explicitly selected framework versions; generated install locks reside in disposable `.consumers`. Network access is required for installation, not widget runtime.
|
|
21
|
+
`validate` runs typecheck, lint, unit tests and JS/declaration/CSS build. `test:consumers` builds, packs and installs the archive in `.consumers/react18`, `.consumers/react19` and `.consumers/next`, checks ESM/CJS and declarations/SSR, and produces application production builds. Consumers use explicitly selected framework versions; generated install locks reside in disposable `.consumers`. Network access is required for installation, not widget runtime.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
### Local Ports and Consumer Servers
|
|
24
|
+
|
|
25
|
+
Browser integration tests use local test servers started by Playwright:
|
|
26
|
+
|
|
27
|
+
- **Port `7311`**: React 18.3.1 consumer application (Vite).
|
|
28
|
+
- **Port `7312`**: React 19.2.0 consumer application with Tailwind CSS 3 (Vite).
|
|
29
|
+
- **Port `7313`**: Next.js 16.2.10 production server (`next start`) testing App Router, Pages Router, and Server Component boundaries.
|
|
30
|
+
|
|
31
|
+
Avoid using these ports for unrelated background processes. If an `EADDRINUSE` error occurs due to an interrupted run, terminate existing node processes holding these ports.
|
|
32
|
+
|
|
33
|
+
### Browser Test Commands
|
|
34
|
+
|
|
35
|
+
- `npm run test:browser`: Executes the full 6-project browser test matrix (React 18 Chromium, React 19 Tailwind Chromium, Next.js App Router Chromium, Firefox, WebKit, and Mobile WebKit emulation).
|
|
36
|
+
- `npm run test:browser:smoke`: Rapid Chromium-only smoke test on the React 18 consumer for fast developer iteration.
|
|
37
|
+
- `CI=1 npm run test:browser`: Disables server reuse in Playwright and forces fresh server lifecycle per run.
|
|
38
|
+
|
|
39
|
+
`npm run example` serves the built-package examples through Vite after `npm run build`. `npm run dev` watches the library JS bundle; run build:css after editing CSS. `npm run test:watch` is useful locally. `npm pack` produces the actual package archive. Never validate only source imports and call it release-ready.
|
|
24
40
|
|
|
25
41
|
## Directory map
|
|
26
42
|
|
|
@@ -77,7 +93,18 @@ These checks require a human/tester; mark results and platform/version in PROJEC
|
|
|
77
93
|
6. Host integration: sticky/fixed overlays, complex forms, embedded media, route navigation, dynamically inserted content and font loading. Confirm each selected setting improves intended content without concealing important controls. Video hiding does not stop playback.
|
|
78
94
|
7. Inspect reset/unmount restoration, rapid reload storage, blocked storage and corrupted saved data. Test a custom feature's restored and removed-control effects.
|
|
79
95
|
|
|
80
|
-
Automated
|
|
96
|
+
### Automated Axe Audits and Human Acceptance
|
|
97
|
+
|
|
98
|
+
Automated `@axe-core/playwright` checks are executed as part of `tests/browser/widget.spec.ts` against the widget DOM (`[data-arap-ui]`) using WCAG 2.0 A/AA, 2.1 AA, and 2.2 AA rule sets in both light and dark host themes.
|
|
99
|
+
|
|
100
|
+
- **Scope:** Automated axe results verify that rendered markup, color contrast within the widget panel, native form controls, and ARIA attributes do not produce detectable programmatic violations.
|
|
101
|
+
- **Non-Certification:** Automated test suites do not establish official WCAG conformance or substitute for human accessibility acceptance. Real screen-reader navigation (VoiceOver, NVDA), physical touch devices, browser zoom (200%/400%), and keyboard reviews are mandatory components of accessibility validation.
|
|
102
|
+
|
|
103
|
+
### Platform and Environment Failure Modes
|
|
104
|
+
|
|
105
|
+
- **macOS Local Firefox Launch:** Firefox on macOS may fail during Playwright launch with `Could not find profile folder`. The complete Firefox test suite passes in Ubuntu Linux CI.
|
|
106
|
+
- **Port Conflicts:** Ensure ports `7311`, `7312`, and `7313` are free before running `npm run test:browser`. If interrupted, kill existing node processes.
|
|
107
|
+
- **Missing Browser Binaries:** If browser engines are missing, execute `npx playwright install --with-deps chromium firefox webkit`.
|
|
81
108
|
|
|
82
109
|
## Release procedure (manual, owner-authorized)
|
|
83
110
|
|
package/docs/FEATURES.md
CHANGED
|
@@ -20,6 +20,20 @@ All features are opt-in via controllers, use native buttons, support Enter/Space
|
|
|
20
20
|
| ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border follows pointer or host focus. Can coexist with mask. |
|
|
21
21
|
| ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
|
|
22
22
|
|
|
23
|
+
## Accessible control primitives and UI states
|
|
24
|
+
|
|
25
|
+
The library exports modular UI primitives conforming to WCAG 2.2 criteria:
|
|
26
|
+
|
|
27
|
+
| Primitive | Accessible Role & State | Key Capabilities |
|
|
28
|
+
| --------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| `ToggleControl` | `role="switch"`, `aria-checked` | Keyboard Space/Enter toggle, disabled/unavailable states, >=44px touch targets (>=48px in largeControls mode). |
|
|
30
|
+
| `ChoiceControl` | `role="radiogroup"`, `role="radio"`, `aria-checked` | Arrow key (Left/Right/Up/Down/Home/End) cycling, check indicators, multi-level/category grouping. |
|
|
31
|
+
| `StepperControl` | `role="group"` with `<output aria-live="polite">` | Accessible increment/decrement buttons, boundary clamping, optional `role="slider"` range input. |
|
|
32
|
+
| `FeatureCard` | `role="group"`, `aria-label` | Card container with title, icon, description, status badge, and alert states (`idle`, `active`, `error`, `unavailable`, `permission-required`). |
|
|
33
|
+
| `SearchCount` | `role="status"`, `aria-live="polite"` | Live status announcement of matched and total features for search filtering. |
|
|
34
|
+
| `EmptyState` / `ErrorState` | `role="status"` / `role="alert"` | Clear messaging with action button for empty results and error recovery. |
|
|
35
|
+
| `ProfilePreviewCard` | `role="group"` | Previews affected settings for accessibility profiles (low-vision, dyslexia, etc.) and provides one-click reversal back to custom settings. |
|
|
36
|
+
|
|
23
37
|
## Original JavaScript and branch comparison
|
|
24
38
|
|
|
25
39
|
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.
|
package/docs/INSTALLATION.md
CHANGED
|
@@ -67,6 +67,12 @@ export default function RootLayout({ children }: { children: ReactNode }) {
|
|
|
67
67
|
|
|
68
68
|
Mount the widget in the persistent root layout, not each route. Do not place document reads inside render. Do not disable SSR merely to mask hydration problems. Effects and portals appear on the client after hydration; a brief default-style paint can occur.
|
|
69
69
|
|
|
70
|
+
A complete runnable example is available in [`examples/next-app/`](../examples/next-app/).
|
|
71
|
+
|
|
72
|
+
## Content Security Policy (CSP)
|
|
73
|
+
|
|
74
|
+
For strict Content Security Policy environments (such as disabling inline styles or generating cryptographic nonces), see the dedicated [Content Security Policy Guidance](CSP.md) for full Next.js and Vite recipes.
|
|
75
|
+
|
|
70
76
|
## Next.js Pages Router
|
|
71
77
|
|
|
72
78
|
```tsx
|
|
@@ -87,7 +93,7 @@ export default function App({ Component, pageProps }: AppProps) {
|
|
|
87
93
|
|
|
88
94
|
Load library CSS after a host reset and load intentional widget overrides afterward. There is no library global preflight. Portals are independent of application layout and filter effects. Global host styles can still affect inherited properties or override selectors, especially with `!important`; inspect computed styles if controls differ.
|
|
89
95
|
|
|
90
|
-
Filters create a containing block for fixed host descendants. Test sticky/fixed headers, modals, menus, images and third-party overlays in your real application. Text measurement does not enter iframe documents or Shadow DOM. Hiding videos is visual only and is not a playback-control feature. See troubleshooting for CSP and font-loading considerations.
|
|
96
|
+
Filters create a containing block for fixed host descendants. Test sticky/fixed headers, modals, menus, images and third-party overlays in your real application. Text measurement does not enter iframe documents or Shadow DOM. Hiding videos is visual only and is not a playback-control feature. See [CSP guidance](CSP.md) and troubleshooting for CSP and font-loading considerations.
|
|
91
97
|
|
|
92
98
|
## Verified consumers
|
|
93
99
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "accessibility-plugin-react",
|
|
3
|
-
"version": "2.3.
|
|
3
|
+
"version": "2.3.2",
|
|
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",
|
|
@@ -36,8 +36,10 @@
|
|
|
36
36
|
"validate": "npm run typecheck && npm run lint && npm test && npm run build",
|
|
37
37
|
"pack:check": "node scripts/check-package.mjs",
|
|
38
38
|
"test:browser": "playwright test",
|
|
39
|
+
"test:browser:smoke": "playwright test --project=react18-chromium",
|
|
39
40
|
"test:consumers": "npm run build && npm run pack:check && node scripts/prepare-consumers.mjs",
|
|
40
41
|
"example": "vite examples",
|
|
42
|
+
"example:next": "npm --prefix examples/next-app run dev",
|
|
41
43
|
"format": "prettier --write src tests scripts examples docs README.md AGENTS.md CHANGELOG.md *.ts *.json *.mjs .github",
|
|
42
44
|
"format:check": "prettier --check src tests scripts examples docs README.md AGENTS.md CHANGELOG.md *.ts *.json *.mjs .github"
|
|
43
45
|
},
|