accessibility-plugin-react 2.2.2 → 2.3.1

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/dist/style.css CHANGED
@@ -701,3 +701,302 @@
701
701
  min-width: 48px;
702
702
  min-height: 48px;
703
703
  }
704
+
705
+ /* Feature Cards, Control Primitives, State UI, and Profile Previews */
706
+ .arap-feature-card {
707
+ display: flex;
708
+ flex-direction: column;
709
+ align-items: stretch;
710
+ gap: 12px;
711
+ }
712
+ .arap-card-header {
713
+ display: flex;
714
+ align-items: center;
715
+ justify-content: space-between;
716
+ gap: 8px;
717
+ }
718
+ .arap-card-title {
719
+ font-weight: 600;
720
+ font-size: 15px;
721
+ color: var(--arap-text);
722
+ }
723
+ .arap-card-desc {
724
+ margin: 0;
725
+ font-size: 13px;
726
+ color: var(--arap-muted);
727
+ line-height: 1.4;
728
+ }
729
+ .arap-status-badge {
730
+ display: inline-flex;
731
+ align-items: center;
732
+ padding: 2px 8px;
733
+ border-radius: 9999px;
734
+ font-size: 11px;
735
+ font-weight: 600;
736
+ background: var(--arap-control);
737
+ border: 1px solid var(--arap-border);
738
+ color: var(--arap-muted);
739
+ text-transform: uppercase;
740
+ letter-spacing: 0.05em;
741
+ }
742
+ .arap-card-alert {
743
+ display: flex;
744
+ align-items: flex-start;
745
+ gap: 8px;
746
+ padding: 10px 12px;
747
+ border-radius: 8px;
748
+ font-size: 13px;
749
+ line-height: 1.4;
750
+ }
751
+ .arap-alert-icon {
752
+ flex: none;
753
+ font-size: 16px;
754
+ line-height: 1;
755
+ }
756
+ .arap-card-error {
757
+ background: #fef2f2;
758
+ border: 1px solid #fecaca;
759
+ color: #991b1b;
760
+ }
761
+ .arap-card-unavailable {
762
+ background: #f8fafc;
763
+ border: 1px solid var(--arap-border);
764
+ color: var(--arap-muted);
765
+ }
766
+ .arap-card-permission {
767
+ background: #fffbeb;
768
+ border: 1px solid #fde68a;
769
+ color: #92400e;
770
+ }
771
+ .arap-permission-content {
772
+ display: flex;
773
+ flex-direction: column;
774
+ gap: 6px;
775
+ }
776
+ .arap-permission-btn {
777
+ align-self: flex-start;
778
+ padding: 4px 10px;
779
+ border: 1px solid #d97706;
780
+ border-radius: 6px;
781
+ background: #f59e0b;
782
+ color: #fff;
783
+ font-size: 12px;
784
+ font-weight: 600;
785
+ cursor: pointer;
786
+ }
787
+ .arap-permission-btn:hover {
788
+ background: #d97706;
789
+ }
790
+ .arap-card-content {
791
+ display: flex;
792
+ flex-direction: column;
793
+ gap: 8px;
794
+ }
795
+
796
+ /* Choice control grouping and badges */
797
+ .arap-choice-group {
798
+ display: flex;
799
+ flex-direction: column;
800
+ gap: 6px;
801
+ width: 100%;
802
+ }
803
+ .arap-choice-group-title {
804
+ font-size: 12px;
805
+ font-weight: 600;
806
+ color: var(--arap-muted);
807
+ text-transform: uppercase;
808
+ letter-spacing: 0.05em;
809
+ }
810
+ .arap-choice-badge {
811
+ font-size: 11px;
812
+ padding: 1px 5px;
813
+ border-radius: 4px;
814
+ background: var(--arap-divider);
815
+ color: var(--arap-muted);
816
+ }
817
+ .arap-segment-active .arap-choice-badge {
818
+ background: rgba(255, 255, 255, 0.25);
819
+ color: #fff;
820
+ }
821
+
822
+ /* Stepper slider */
823
+ .arap-stepper-control-wrapper {
824
+ display: flex;
825
+ flex-direction: column;
826
+ gap: 8px;
827
+ width: 100%;
828
+ }
829
+ .arap-slider-container {
830
+ display: flex;
831
+ align-items: center;
832
+ padding: 4px 0;
833
+ }
834
+ .arap-slider {
835
+ width: 100%;
836
+ accent-color: var(--arap-accent);
837
+ cursor: pointer;
838
+ }
839
+
840
+ /* Search Count & Empty State */
841
+ .arap-search-count {
842
+ padding: 6px 0;
843
+ font-size: 12px;
844
+ font-weight: 500;
845
+ color: var(--arap-muted);
846
+ }
847
+ .arap-empty-state {
848
+ display: flex;
849
+ flex-direction: column;
850
+ align-items: center;
851
+ justify-content: center;
852
+ text-align: center;
853
+ padding: 24px 16px;
854
+ gap: 8px;
855
+ }
856
+ .arap-empty-icon {
857
+ font-size: 32px;
858
+ }
859
+ .arap-empty-title {
860
+ margin: 0;
861
+ font-size: 16px;
862
+ font-weight: 600;
863
+ color: var(--arap-text);
864
+ }
865
+ .arap-empty-desc {
866
+ margin: 0;
867
+ font-size: 13px;
868
+ color: var(--arap-muted);
869
+ }
870
+ .arap-empty-btn,
871
+ .arap-retry-btn {
872
+ margin-top: 6px;
873
+ padding: 8px 16px;
874
+ border: 1px solid var(--arap-border);
875
+ border-radius: 8px;
876
+ background: var(--arap-control);
877
+ font-weight: 500;
878
+ font-size: 13px;
879
+ color: var(--arap-text);
880
+ cursor: pointer;
881
+ }
882
+ .arap-empty-btn:hover,
883
+ .arap-retry-btn:hover {
884
+ background: var(--arap-selected);
885
+ border-color: var(--arap-accent);
886
+ color: var(--arap-accent);
887
+ }
888
+
889
+ /* Profile Preview Card */
890
+ .arap-profile-card {
891
+ display: flex;
892
+ flex-direction: column;
893
+ gap: 12px;
894
+ padding: 16px;
895
+ border: 1px solid var(--arap-border);
896
+ border-radius: 12px;
897
+ background: var(--arap-surface);
898
+ transition:
899
+ border-color 0.15s,
900
+ box-shadow 0.15s;
901
+ }
902
+ .arap-profile-card-active {
903
+ border-color: var(--arap-accent);
904
+ background: var(--arap-selected);
905
+ box-shadow: 0 0 0 1px var(--arap-accent);
906
+ }
907
+ .arap-profile-header {
908
+ display: flex;
909
+ flex-direction: column;
910
+ gap: 4px;
911
+ }
912
+ .arap-profile-title-row {
913
+ display: flex;
914
+ align-items: center;
915
+ justify-content: space-between;
916
+ gap: 8px;
917
+ }
918
+ .arap-profile-title {
919
+ margin: 0;
920
+ font-size: 15px;
921
+ font-weight: 600;
922
+ color: var(--arap-text);
923
+ }
924
+ .arap-profile-active-badge {
925
+ font-size: 11px;
926
+ font-weight: 600;
927
+ color: var(--arap-accent);
928
+ background: #dbeafe;
929
+ padding: 2px 8px;
930
+ border-radius: 9999px;
931
+ }
932
+ .arap-profile-desc {
933
+ margin: 0;
934
+ font-size: 13px;
935
+ color: var(--arap-muted);
936
+ line-height: 1.4;
937
+ }
938
+ .arap-profile-affected {
939
+ display: flex;
940
+ flex-direction: column;
941
+ gap: 6px;
942
+ }
943
+ .arap-profile-affected-label {
944
+ font-size: 11px;
945
+ font-weight: 600;
946
+ color: var(--arap-muted);
947
+ text-transform: uppercase;
948
+ letter-spacing: 0.05em;
949
+ }
950
+ .arap-profile-chips {
951
+ display: flex;
952
+ flex-wrap: wrap;
953
+ gap: 6px;
954
+ }
955
+ .arap-profile-chip {
956
+ display: inline-flex;
957
+ align-items: center;
958
+ gap: 4px;
959
+ padding: 3px 8px;
960
+ border-radius: 6px;
961
+ background: var(--arap-control);
962
+ border: 1px solid var(--arap-divider);
963
+ font-size: 12px;
964
+ color: var(--arap-text);
965
+ }
966
+ .arap-profile-actions {
967
+ display: flex;
968
+ gap: 8px;
969
+ margin-top: 4px;
970
+ }
971
+ .arap-profile-apply-btn {
972
+ flex: 1;
973
+ padding: 8px 14px;
974
+ border: 1px solid var(--arap-accent);
975
+ border-radius: 8px;
976
+ background: var(--arap-accent);
977
+ color: #fff;
978
+ font-size: 13px;
979
+ font-weight: 600;
980
+ cursor: pointer;
981
+ text-align: center;
982
+ }
983
+ .arap-profile-apply-btn:hover {
984
+ background: var(--arap-accent-hover);
985
+ }
986
+ .arap-profile-revert-btn {
987
+ flex: 1;
988
+ padding: 8px 14px;
989
+ border: 1px solid var(--arap-border);
990
+ border-radius: 8px;
991
+ background: var(--arap-surface);
992
+ color: var(--arap-muted);
993
+ font-size: 13px;
994
+ font-weight: 600;
995
+ cursor: pointer;
996
+ text-align: center;
997
+ }
998
+ .arap-profile-revert-btn:hover {
999
+ background: var(--arap-control);
1000
+ color: var(--arap-text);
1001
+ border-color: var(--arap-text);
1002
+ }
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,14 +70,14 @@ 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.
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
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.
82
82
 
83
83
  ### M2 — Stable visual and typographic features
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/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.2.2",
3
+ "version": "2.3.1",
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",
@@ -38,6 +38,7 @@
38
38
  "test:browser": "playwright test",
39
39
  "test:consumers": "npm run build && npm run pack:check && node scripts/prepare-consumers.mjs",
40
40
  "example": "vite examples",
41
+ "example:next": "npm --prefix examples/next-app run dev",
41
42
  "format": "prettier --write src tests scripts examples docs README.md AGENTS.md CHANGELOG.md *.ts *.json *.mjs .github",
42
43
  "format:check": "prettier --check src tests scripts examples docs README.md AGENTS.md CHANGELOG.md *.ts *.json *.mjs .github"
43
44
  },