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 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.2` patch release adds automatic widget stylesheet injection on package
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 (empty string omits it); `closeLabel?: string` default Close accessibility settings; `className?: string`; `style?: CSSProperties` |
12
- | All fifteen controllers listed in FEATURES.md | No props. Pick/omit in JSX. For custom labels or behavior, compose a control with useAccessibility. |
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
- - [ ] [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
- - [ ] [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
- - [ ] [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
- - [ ] [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
- - [ ] [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
- - [ ] [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
- - [ ] [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
- - [ ] [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
- - [ ] [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.
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 |
@@ -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. Browser tests start local ports 7311/7312/7313 and close their servers afterward. Avoid using these ports for unrelated processes. `CI` disables server reuse and is a test-runner environment flag, not a library setting.
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
- `npm run example` serves the two 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.
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 axe results cover the tested widget DOM and criteria tags; they neither certify the host nor cover all assistive-technology behavior.
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.
@@ -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.0",
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
  },