accessibility-plugin-react 2.3.1 → 2.4.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.
package/docs/API.md CHANGED
@@ -4,18 +4,19 @@ 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; `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. |
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
+ | TextScaleController | `steps?: readonly number[]` default `[1.0, 1.125, 1.25, 1.5, 2.0]`; `label?: string` default `Bigger Text`. Stepped text scaling without transforms. |
18
+ | FontSizeController | Optional `stepScale?: boolean` (snaps to WCAG 1x–2x reflow steps); `steps?: readonly number[]` (custom steps); or omitted for continuous 10% steps. Protects forms, code, and icons. |
19
+ | All other controllers in FEATURES.md | Pick/omit in JSX. For custom labels or behavior, compose a control with useAccessibility or the modular control primitives. |
19
20
 
20
21
  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.
21
22
 
@@ -43,9 +44,11 @@ Definitions/defaults are immutable for the provider lifetime; the first register
43
44
 
44
45
  `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.
45
46
 
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
+ Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions<T>`, `FeatureRegistration`, `ToggleControlProps`, `ChoiceControlProps`, `ChoiceOption<T>`, `ChoiceGroup<T>`, `StepperControlProps`, `FeatureCardProps`, `FeatureStatus`, `SearchCountProps`, `EmptyStateProps`, `ErrorStateProps`, `ProfilePreviewCardProps`, `FontSizeControllerProps`, `TextScaleControllerProps`, `TextScaleStep`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`.
47
48
 
48
- Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`.
49
+ Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`.
50
+
51
+ Exported typography and reflow utilities: `TEXT_SCALE_STEPS`, `TEXT_SCALE_PROTECTED_SELECTOR`, `isProtectedFromTextScale`.
49
52
 
50
53
  Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
51
54
 
@@ -78,11 +78,11 @@ completed. Closing a child issue does not replace the milestone exit review.
78
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
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
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
- - [ ] [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.
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
 
85
- - [ ] [A11Y-201 — Bigger text and reflow-safe scaling #41](https://github.com/prabothcharith/accessibility-react/issues/41) — Add stepwise 1x–2x text scaling through reflow-safe scoped styles without nested compounding, clipping or changes to protected controls.
85
+ - [x] [A11Y-201 — Bigger text and reflow-safe scaling #41](https://github.com/prabothcharith/accessibility-react/issues/41) — Add stepwise 1x–2x text scaling through reflow-safe scoped styles without nested compounding, clipping or changes to protected controls.
86
86
  - [ ] [A11Y-202 — Letter, word, paragraph spacing and line height #42](https://github.com/prabothcharith/accessibility-react/issues/42) — Add independent letter, word and paragraph spacing plus line-height options with script-aware limits and restoration tests.
87
87
  - [ ] [A11Y-203 — Text alignment, legible fonts and language fallback #43](https://github.com/prabothcharith/accessibility-react/issues/43) — Add scoped text alignment and legally distributable readable font choices with Sinhala/Tamil fallbacks while protecting icons, code and symbols.
88
88
  - [ ] [A11Y-204 — Contrast modes and native forced-color protection #44](https://github.com/prabothcharith/accessibility-react/issues/44) — Add targeted original/light/dark/high/invert contrast modes that preserve host content and respect forced colors and other native settings.
@@ -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
@@ -4,7 +4,8 @@ All features are opt-in via controllers, use native buttons, support Enter/Space
4
4
 
5
5
  | Controller / key | Default; states and bounds | Host behavior / edge cases |
6
6
  | --------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7
- | FontSizeController / fontSize | 100; 50–200%, step 10 | Scales each computed HTML element font size and line height together. Stops at bounds; not a substitute for browser zoom. |
7
+ | 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. |
8
+ | 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. |
8
9
  | LineHeightController / lineHeight | 100; 50–200%, step 10 | Scales existing computed line height, multiplied by active font scale. Normal line height uses 1.2× font approximation. |
9
10
  | LetterSpacingController / letterSpacing | 0; 0–10px, step 1 | Nonzero value sets spacing on HTML descendants. Zero restores host. |
10
11
  | ContrastController / contrast | 0; 0/1/2/3, reduced, yellow-on-black, white-on-black, blue-on-yellow | Off, 1.25×, 1.5×, 2×; reduced=0.5×. Named palettes set foreground/background instead of contrast filter. Palette doesn't guarantee contrast of all rendered content. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "accessibility-plugin-react",
3
- "version": "2.3.1",
3
+ "version": "2.4.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",
@@ -36,6 +36,7 @@
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",
41
42
  "example:next": "npm --prefix examples/next-app run dev",