accessibility-plugin-react 2.0.1 → 2.2.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/README.md CHANGED
@@ -4,10 +4,10 @@ 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.1` patch release updates the published v2 documentation without
8
- changing the runtime API. It supports React 18.3.1 and React 19.x, ships ESM,
9
- CommonJS, TypeScript declarations, and scoped plain CSS, and has no runtime
10
- dependency other than React and React DOM.
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.
9
+ It supports React 18.3.1 and React 19.x, ships ESM, CommonJS, TypeScript declarations,
10
+ and scoped plain CSS, and has no runtime dependency other than React and React DOM.
11
11
 
12
12
  > This library improves the presentation of your content. It cannot repair
13
13
  > inaccessible application markup or certify WCAG conformance. Human
@@ -29,8 +29,9 @@ Tailwind, Motion, or an icon library.
29
29
 
30
30
  ## Quick start
31
31
 
32
- Import the stylesheet once and mount one provider per document, preferably
33
- above route changes or in the persistent application layout:
32
+ Import the package and mount one provider per document, preferably above route
33
+ changes or in the persistent application layout. The package automatically
34
+ injects its scoped CSS in browser environments:
34
35
 
35
36
  ```tsx
36
37
  import {
@@ -42,7 +43,6 @@ import {
42
43
  GrayscaleController,
43
44
  ResetController,
44
45
  } from "accessibility-plugin-react";
45
- import "accessibility-plugin-react/style.css";
46
46
 
47
47
  export function AccessibilitySettings() {
48
48
  return (
package/dist/index.d.mts CHANGED
@@ -1,6 +1,118 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode, CSSProperties } from 'react';
3
3
 
4
+ type ContrastMode = "off" | "light" | "dark" | "high" | "invert";
5
+ type ReaderMode = "off" | "guide" | "mask";
6
+ type StorageMode = "none" | "session" | "local";
7
+ type TextAlignPreference = "original" | "left" | "right" | "center" | "justify";
8
+ type FontFamilyPreference = "original" | "legible" | "dyslexia-option";
9
+ type CursorSizePreference = "original" | "large";
10
+ type SaturationPreference = "original" | "low" | "high" | "grayscale";
11
+ interface AccessibilityPreferences {
12
+ /** Relative scale: 0.5 to 2.0 (1.0 = original). */
13
+ fontScale: number;
14
+ /** Relative scale: 0.5 to 2.0, or null for site original. */
15
+ lineHeight: number | null;
16
+ /** Letter spacing in em: 0.0 to 0.5, or null for site original. */
17
+ letterSpacingEm: number | null;
18
+ /** Word spacing in em: 0.0 to 0.5, or null for site original. */
19
+ wordSpacingEm: number | null;
20
+ /** Paragraph spacing in em: 0.0 to 1.0, or null for site original. */
21
+ paragraphSpacingEm: number | null;
22
+ textAlign: TextAlignPreference;
23
+ contrastMode: ContrastMode;
24
+ highlightLinks: boolean;
25
+ highlightFocus: boolean;
26
+ reduceMotion: boolean;
27
+ hideDecorativeImages: boolean;
28
+ fontFamily: FontFamilyPreference;
29
+ cursorSize: CursorSizePreference;
30
+ readerMode: ReaderMode;
31
+ saturation: SaturationPreference;
32
+ tooltips: boolean;
33
+ }
34
+ type ProfilePresetId = "motor" | "blind" | "color-blind" | "dyslexia" | "low-vision" | "cognitive" | "seizure" | "adhd";
35
+ interface ProfileDefinition {
36
+ id: ProfilePresetId;
37
+ label: string;
38
+ description: string;
39
+ settings: Partial<AccessibilityPreferences>;
40
+ }
41
+ interface PreferencesState {
42
+ /** Base preferences configured before any profile was selected. */
43
+ base: AccessibilityPreferences;
44
+ /** Active profile preset identifier, if any. */
45
+ activeProfileId: ProfilePresetId | null;
46
+ /** Snapshot of settings applied by the current active profile. */
47
+ profileSnapshot: Partial<AccessibilityPreferences> | null;
48
+ /** User explicit overrides applied on top of the active profile. */
49
+ overrides: Partial<AccessibilityPreferences>;
50
+ /** Effective resolved preferences combining defaults, base, profile, and overrides. */
51
+ effective: AccessibilityPreferences;
52
+ }
53
+ type PreferencesAction = {
54
+ type: "SET_PREFERENCE";
55
+ key: keyof AccessibilityPreferences;
56
+ value: AccessibilityPreferences[keyof AccessibilityPreferences];
57
+ } | {
58
+ type: "APPLY_PROFILE";
59
+ profileId: ProfilePresetId;
60
+ settings: Partial<AccessibilityPreferences>;
61
+ } | {
62
+ type: "CLEAR_PROFILE";
63
+ } | {
64
+ type: "RESET_ALL";
65
+ } | {
66
+ type: "IMPORT_PREFERENCES";
67
+ preferences: Partial<AccessibilityPreferences>;
68
+ };
69
+
70
+ declare const DEFAULT_PREFERENCES: Readonly<AccessibilityPreferences>;
71
+ declare const PROFILE_DEFINITIONS: Record<ProfilePresetId, ProfileDefinition>;
72
+
73
+ declare function normalizePreferenceValue<K extends keyof AccessibilityPreferences>(key: K, value: unknown): AccessibilityPreferences[K];
74
+ declare function normalizePreferences(input?: Partial<AccessibilityPreferences> | null): AccessibilityPreferences;
75
+ declare function resolveEffectivePreferences(base: AccessibilityPreferences, profileSnapshot: Partial<AccessibilityPreferences> | null, overrides: Partial<AccessibilityPreferences>): AccessibilityPreferences;
76
+
77
+ declare function createInitialPreferencesState(initial?: Partial<AccessibilityPreferences> | null): PreferencesState;
78
+ declare function preferencesReducer(state: PreferencesState, action: PreferencesAction): PreferencesState;
79
+
80
+ interface LocaleStrings {
81
+ title: string;
82
+ description: string;
83
+ closeLabel: string;
84
+ skipToActions: string;
85
+ toolsLabel: string;
86
+ quickActionsLabel: string;
87
+ resetLabel: string;
88
+ resetAll: string;
89
+ statementLink: string;
90
+ openInNewTab: string;
91
+ buttonTitle: string;
92
+ dragHelp: string;
93
+ positionLabel: string;
94
+ moveButton: string;
95
+ moveButtonLabel: string;
96
+ buttonPositionSelectLabel: string;
97
+ customPosition: string;
98
+ resetPosition: string;
99
+ doneMoving: string;
100
+ moveLeft: string;
101
+ moveUp: string;
102
+ moveDown: string;
103
+ moveRight: string;
104
+ largeControlsLabel: string;
105
+ formatPointPosition?: (x: number, y: number) => string;
106
+ formatCornerPosition?: (corner: string) => string;
107
+ }
108
+ type SupportedLocale = "en" | string;
109
+
110
+ declare const enLocale: Readonly<LocaleStrings>;
111
+
112
+ declare function registerLocale(code: string, strings: LocaleStrings): void;
113
+ declare function isRtlLocale(localeProp?: string): boolean;
114
+ declare function resolveLocaleStrings(localeProp?: string): LocaleStrings;
115
+
4
116
  interface AccessibilityState {
5
117
  isOpen: boolean;
6
118
  features: Record<string, unknown>;
@@ -29,6 +141,9 @@ interface AccessibilityContextValue {
29
141
  resetAll: () => void;
30
142
  registerReset: (key: string, resetFn: () => void) => void;
31
143
  unregisterReset: (key: string) => void;
144
+ locale?: string;
145
+ statementUrl?: string;
146
+ largeControls?: boolean;
32
147
  }
33
148
  type WidgetPlacement = {
34
149
  kind: "corner";
@@ -38,13 +153,22 @@ type WidgetPlacement = {
38
153
  x: number;
39
154
  y: number;
40
155
  };
156
+
41
157
  type PluginPosition = "left" | "right" | "top" | "bottom";
42
158
  interface AccessibilityPluginProps {
43
159
  children: ReactNode;
44
160
  position?: PluginPosition;
45
161
  persistenceKey?: string;
46
- /** Disable storage completely. */
162
+ /** Disable storage completely (backward-compatible alias for storage="none"). */
47
163
  persist?: boolean;
164
+ /** Storage mode: 'none' | 'session' | 'local'. Defaults to 'local'. */
165
+ storage?: StorageMode;
166
+ /** Preferred UI language locale (defaults to html lang or 'en'). */
167
+ locale?: string;
168
+ /** Real URL to site owner's accessibility statement (W-22). */
169
+ statementUrl?: string;
170
+ /** Oversized widget controls mode (>=48px touch targets, W-21). */
171
+ largeControls?: boolean;
48
172
  }
49
173
  interface AccessibilityButtonProps {
50
174
  /** Pointer dragging and Alt+Arrow movement. Defaults to true. */
@@ -54,6 +178,7 @@ interface AccessibilityButtonProps {
54
178
  description?: string;
55
179
  className?: string;
56
180
  style?: CSSProperties;
181
+ largeControls?: boolean;
57
182
  }
58
183
  interface AccessibilityListProps {
59
184
  /** Additional always-visible actions next to ResetController. */
@@ -65,11 +190,17 @@ interface AccessibilityListProps {
65
190
  style?: CSSProperties;
66
191
  title?: string;
67
192
  closeLabel?: string;
193
+ /** Real URL to site owner's accessibility statement (W-22). */
194
+ statementUrl?: string;
195
+ /** Oversized widget controls mode (>=48px touch targets, W-21). */
196
+ largeControls?: boolean;
197
+ /** Preferred UI language locale. */
198
+ locale?: string;
68
199
  }
69
200
 
70
- declare function AccessibilityPlugin({ children, position, persistenceKey, persist, }: AccessibilityPluginProps): react.JSX.Element;
201
+ declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, }: AccessibilityPluginProps): react.JSX.Element;
71
202
 
72
- declare function AccessibilityButton({ icon, draggable, title, description, className, style, }: AccessibilityButtonProps): react.JSX.Element;
203
+ declare function AccessibilityButton({ icon, draggable, title, description, className, style, largeControls, }: AccessibilityButtonProps): react.JSX.Element;
73
204
 
74
205
  declare function AccessibilityList(props: AccessibilityListProps): react.JSX.Element;
75
206
 
@@ -111,4 +242,4 @@ declare function ReadingGuideController(): react.JSX.Element;
111
242
 
112
243
  declare function ResetController(): react.JSX.Element;
113
244
 
114
- export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityState, BigCursorController, ContrastController, type FeatureOptions, type FeatureRegistration, FontSizeController, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LetterSpacingController, LineHeightController, LinkHighlightController, type PluginPosition, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, TextAlignController, type WidgetPlacement, useAccessibility };
245
+ export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, type AccessibilityState, BigCursorController, ContrastController, type ContrastMode, type CursorSizePreference, DEFAULT_PREFERENCES, type FeatureOptions, type FeatureRegistration, type FontFamilyPreference, FontSizeController, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LetterSpacingController, LineHeightController, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, type PluginPosition, type ProfileDefinition, type ProfilePresetId, type ReaderMode, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, type SaturationPreference, type StorageMode, type SupportedLocale, TextAlignController, type TextAlignPreference, type WidgetPlacement, createInitialPreferencesState, enLocale, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,118 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode, CSSProperties } from 'react';
3
3
 
4
+ type ContrastMode = "off" | "light" | "dark" | "high" | "invert";
5
+ type ReaderMode = "off" | "guide" | "mask";
6
+ type StorageMode = "none" | "session" | "local";
7
+ type TextAlignPreference = "original" | "left" | "right" | "center" | "justify";
8
+ type FontFamilyPreference = "original" | "legible" | "dyslexia-option";
9
+ type CursorSizePreference = "original" | "large";
10
+ type SaturationPreference = "original" | "low" | "high" | "grayscale";
11
+ interface AccessibilityPreferences {
12
+ /** Relative scale: 0.5 to 2.0 (1.0 = original). */
13
+ fontScale: number;
14
+ /** Relative scale: 0.5 to 2.0, or null for site original. */
15
+ lineHeight: number | null;
16
+ /** Letter spacing in em: 0.0 to 0.5, or null for site original. */
17
+ letterSpacingEm: number | null;
18
+ /** Word spacing in em: 0.0 to 0.5, or null for site original. */
19
+ wordSpacingEm: number | null;
20
+ /** Paragraph spacing in em: 0.0 to 1.0, or null for site original. */
21
+ paragraphSpacingEm: number | null;
22
+ textAlign: TextAlignPreference;
23
+ contrastMode: ContrastMode;
24
+ highlightLinks: boolean;
25
+ highlightFocus: boolean;
26
+ reduceMotion: boolean;
27
+ hideDecorativeImages: boolean;
28
+ fontFamily: FontFamilyPreference;
29
+ cursorSize: CursorSizePreference;
30
+ readerMode: ReaderMode;
31
+ saturation: SaturationPreference;
32
+ tooltips: boolean;
33
+ }
34
+ type ProfilePresetId = "motor" | "blind" | "color-blind" | "dyslexia" | "low-vision" | "cognitive" | "seizure" | "adhd";
35
+ interface ProfileDefinition {
36
+ id: ProfilePresetId;
37
+ label: string;
38
+ description: string;
39
+ settings: Partial<AccessibilityPreferences>;
40
+ }
41
+ interface PreferencesState {
42
+ /** Base preferences configured before any profile was selected. */
43
+ base: AccessibilityPreferences;
44
+ /** Active profile preset identifier, if any. */
45
+ activeProfileId: ProfilePresetId | null;
46
+ /** Snapshot of settings applied by the current active profile. */
47
+ profileSnapshot: Partial<AccessibilityPreferences> | null;
48
+ /** User explicit overrides applied on top of the active profile. */
49
+ overrides: Partial<AccessibilityPreferences>;
50
+ /** Effective resolved preferences combining defaults, base, profile, and overrides. */
51
+ effective: AccessibilityPreferences;
52
+ }
53
+ type PreferencesAction = {
54
+ type: "SET_PREFERENCE";
55
+ key: keyof AccessibilityPreferences;
56
+ value: AccessibilityPreferences[keyof AccessibilityPreferences];
57
+ } | {
58
+ type: "APPLY_PROFILE";
59
+ profileId: ProfilePresetId;
60
+ settings: Partial<AccessibilityPreferences>;
61
+ } | {
62
+ type: "CLEAR_PROFILE";
63
+ } | {
64
+ type: "RESET_ALL";
65
+ } | {
66
+ type: "IMPORT_PREFERENCES";
67
+ preferences: Partial<AccessibilityPreferences>;
68
+ };
69
+
70
+ declare const DEFAULT_PREFERENCES: Readonly<AccessibilityPreferences>;
71
+ declare const PROFILE_DEFINITIONS: Record<ProfilePresetId, ProfileDefinition>;
72
+
73
+ declare function normalizePreferenceValue<K extends keyof AccessibilityPreferences>(key: K, value: unknown): AccessibilityPreferences[K];
74
+ declare function normalizePreferences(input?: Partial<AccessibilityPreferences> | null): AccessibilityPreferences;
75
+ declare function resolveEffectivePreferences(base: AccessibilityPreferences, profileSnapshot: Partial<AccessibilityPreferences> | null, overrides: Partial<AccessibilityPreferences>): AccessibilityPreferences;
76
+
77
+ declare function createInitialPreferencesState(initial?: Partial<AccessibilityPreferences> | null): PreferencesState;
78
+ declare function preferencesReducer(state: PreferencesState, action: PreferencesAction): PreferencesState;
79
+
80
+ interface LocaleStrings {
81
+ title: string;
82
+ description: string;
83
+ closeLabel: string;
84
+ skipToActions: string;
85
+ toolsLabel: string;
86
+ quickActionsLabel: string;
87
+ resetLabel: string;
88
+ resetAll: string;
89
+ statementLink: string;
90
+ openInNewTab: string;
91
+ buttonTitle: string;
92
+ dragHelp: string;
93
+ positionLabel: string;
94
+ moveButton: string;
95
+ moveButtonLabel: string;
96
+ buttonPositionSelectLabel: string;
97
+ customPosition: string;
98
+ resetPosition: string;
99
+ doneMoving: string;
100
+ moveLeft: string;
101
+ moveUp: string;
102
+ moveDown: string;
103
+ moveRight: string;
104
+ largeControlsLabel: string;
105
+ formatPointPosition?: (x: number, y: number) => string;
106
+ formatCornerPosition?: (corner: string) => string;
107
+ }
108
+ type SupportedLocale = "en" | string;
109
+
110
+ declare const enLocale: Readonly<LocaleStrings>;
111
+
112
+ declare function registerLocale(code: string, strings: LocaleStrings): void;
113
+ declare function isRtlLocale(localeProp?: string): boolean;
114
+ declare function resolveLocaleStrings(localeProp?: string): LocaleStrings;
115
+
4
116
  interface AccessibilityState {
5
117
  isOpen: boolean;
6
118
  features: Record<string, unknown>;
@@ -29,6 +141,9 @@ interface AccessibilityContextValue {
29
141
  resetAll: () => void;
30
142
  registerReset: (key: string, resetFn: () => void) => void;
31
143
  unregisterReset: (key: string) => void;
144
+ locale?: string;
145
+ statementUrl?: string;
146
+ largeControls?: boolean;
32
147
  }
33
148
  type WidgetPlacement = {
34
149
  kind: "corner";
@@ -38,13 +153,22 @@ type WidgetPlacement = {
38
153
  x: number;
39
154
  y: number;
40
155
  };
156
+
41
157
  type PluginPosition = "left" | "right" | "top" | "bottom";
42
158
  interface AccessibilityPluginProps {
43
159
  children: ReactNode;
44
160
  position?: PluginPosition;
45
161
  persistenceKey?: string;
46
- /** Disable storage completely. */
162
+ /** Disable storage completely (backward-compatible alias for storage="none"). */
47
163
  persist?: boolean;
164
+ /** Storage mode: 'none' | 'session' | 'local'. Defaults to 'local'. */
165
+ storage?: StorageMode;
166
+ /** Preferred UI language locale (defaults to html lang or 'en'). */
167
+ locale?: string;
168
+ /** Real URL to site owner's accessibility statement (W-22). */
169
+ statementUrl?: string;
170
+ /** Oversized widget controls mode (>=48px touch targets, W-21). */
171
+ largeControls?: boolean;
48
172
  }
49
173
  interface AccessibilityButtonProps {
50
174
  /** Pointer dragging and Alt+Arrow movement. Defaults to true. */
@@ -54,6 +178,7 @@ interface AccessibilityButtonProps {
54
178
  description?: string;
55
179
  className?: string;
56
180
  style?: CSSProperties;
181
+ largeControls?: boolean;
57
182
  }
58
183
  interface AccessibilityListProps {
59
184
  /** Additional always-visible actions next to ResetController. */
@@ -65,11 +190,17 @@ interface AccessibilityListProps {
65
190
  style?: CSSProperties;
66
191
  title?: string;
67
192
  closeLabel?: string;
193
+ /** Real URL to site owner's accessibility statement (W-22). */
194
+ statementUrl?: string;
195
+ /** Oversized widget controls mode (>=48px touch targets, W-21). */
196
+ largeControls?: boolean;
197
+ /** Preferred UI language locale. */
198
+ locale?: string;
68
199
  }
69
200
 
70
- declare function AccessibilityPlugin({ children, position, persistenceKey, persist, }: AccessibilityPluginProps): react.JSX.Element;
201
+ declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, }: AccessibilityPluginProps): react.JSX.Element;
71
202
 
72
- declare function AccessibilityButton({ icon, draggable, title, description, className, style, }: AccessibilityButtonProps): react.JSX.Element;
203
+ declare function AccessibilityButton({ icon, draggable, title, description, className, style, largeControls, }: AccessibilityButtonProps): react.JSX.Element;
73
204
 
74
205
  declare function AccessibilityList(props: AccessibilityListProps): react.JSX.Element;
75
206
 
@@ -111,4 +242,4 @@ declare function ReadingGuideController(): react.JSX.Element;
111
242
 
112
243
  declare function ResetController(): react.JSX.Element;
113
244
 
114
- export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityState, BigCursorController, ContrastController, type FeatureOptions, type FeatureRegistration, FontSizeController, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LetterSpacingController, LineHeightController, LinkHighlightController, type PluginPosition, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, TextAlignController, type WidgetPlacement, useAccessibility };
245
+ export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, type AccessibilityState, BigCursorController, ContrastController, type ContrastMode, type CursorSizePreference, DEFAULT_PREFERENCES, type FeatureOptions, type FeatureRegistration, type FontFamilyPreference, FontSizeController, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LetterSpacingController, LineHeightController, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, type PluginPosition, type ProfileDefinition, type ProfilePresetId, type ReaderMode, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, type SaturationPreference, type StorageMode, type SupportedLocale, TextAlignController, type TextAlignPreference, type WidgetPlacement, createInitialPreferencesState, enLocale, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };