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/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/dist/index.d.mts CHANGED
@@ -113,6 +113,125 @@ declare function registerLocale(code: string, strings: LocaleStrings): void;
113
113
  declare function isRtlLocale(localeProp?: string): boolean;
114
114
  declare function resolveLocaleStrings(localeProp?: string): LocaleStrings;
115
115
 
116
+ interface ToggleControlProps {
117
+ id?: string;
118
+ label: ReactNode;
119
+ checked: boolean;
120
+ onChange: (checked: boolean) => void;
121
+ disabled?: boolean;
122
+ unavailable?: boolean;
123
+ unavailableReason?: string;
124
+ name?: string;
125
+ description?: string;
126
+ largeControls?: boolean;
127
+ className?: string;
128
+ style?: CSSProperties;
129
+ }
130
+ declare function ToggleControl({ id, label, checked, onChange, disabled, unavailable, unavailableReason, name, description, largeControls, className, style, }: ToggleControlProps): react.JSX.Element;
131
+
132
+ interface ChoiceOption<T extends string | number> {
133
+ label: string;
134
+ value: T;
135
+ description?: string;
136
+ disabled?: boolean;
137
+ badge?: string;
138
+ }
139
+ interface ChoiceGroup<T extends string | number> {
140
+ label: string;
141
+ options: ChoiceOption<T>[];
142
+ }
143
+ interface ChoiceControlProps<T extends string | number> {
144
+ id?: string;
145
+ label: string;
146
+ value: T;
147
+ options?: ChoiceOption<T>[];
148
+ groups?: ChoiceGroup<T>[];
149
+ onChange: (value: T) => void;
150
+ disabled?: boolean;
151
+ largeControls?: boolean;
152
+ className?: string;
153
+ style?: CSSProperties;
154
+ orientation?: "horizontal" | "vertical";
155
+ }
156
+ declare function ChoiceControl<T extends string | number>({ id, label, value, options, groups, onChange, disabled, largeControls, className, style, orientation, }: ChoiceControlProps<T>): react.JSX.Element;
157
+
158
+ interface StepperControlProps {
159
+ id?: string;
160
+ label: string;
161
+ value: number;
162
+ min: number;
163
+ max: number;
164
+ step: number;
165
+ unit?: string;
166
+ formatValue?: (val: number) => string;
167
+ onChange: (value: number) => void;
168
+ showSlider?: boolean;
169
+ disabled?: boolean;
170
+ largeControls?: boolean;
171
+ className?: string;
172
+ style?: CSSProperties;
173
+ }
174
+ declare function StepperControl({ id, label, value, min, max, step, unit, formatValue, onChange, showSlider, disabled, largeControls, className, style, }: StepperControlProps): react.JSX.Element;
175
+
176
+ type FeatureStatus = "idle" | "active" | "error" | "unavailable" | "permission-required";
177
+ interface FeatureCardProps {
178
+ id?: string;
179
+ featureKey?: string;
180
+ icon?: ReactNode;
181
+ title: ReactNode;
182
+ description?: ReactNode;
183
+ statusBadge?: string;
184
+ status?: FeatureStatus;
185
+ errorMessage?: string;
186
+ unavailableMessage?: string;
187
+ permissionMessage?: string;
188
+ onRequestPermission?: () => void;
189
+ children: ReactNode;
190
+ className?: string;
191
+ style?: CSSProperties;
192
+ largeControls?: boolean;
193
+ }
194
+ declare function FeatureCard({ id, featureKey, icon, title, description, statusBadge, status, errorMessage, unavailableMessage, permissionMessage, onRequestPermission, children, className, style, largeControls, }: FeatureCardProps): react.JSX.Element;
195
+
196
+ interface SearchCountProps {
197
+ totalCount: number;
198
+ matchedCount: number;
199
+ query?: string;
200
+ className?: string;
201
+ style?: CSSProperties;
202
+ }
203
+ declare function SearchCount({ totalCount, matchedCount, query, className, style, }: SearchCountProps): react.JSX.Element;
204
+ interface EmptyStateProps {
205
+ title?: string;
206
+ description?: string;
207
+ actionLabel?: string;
208
+ onAction?: () => void;
209
+ icon?: ReactNode;
210
+ className?: string;
211
+ style?: CSSProperties;
212
+ }
213
+ declare function EmptyState({ title, description, actionLabel, onAction, icon, className, style, }: EmptyStateProps): react.JSX.Element;
214
+ interface ErrorStateProps {
215
+ title?: string;
216
+ message: string;
217
+ onRetry?: () => void;
218
+ retryLabel?: string;
219
+ className?: string;
220
+ style?: CSSProperties;
221
+ }
222
+ declare function ErrorState({ title, message, onRetry, retryLabel, className, style, }: ErrorStateProps): react.JSX.Element;
223
+
224
+ interface ProfilePreviewCardProps {
225
+ profile: ProfileDefinition;
226
+ isActive: boolean;
227
+ onApply: (profile: ProfileDefinition) => void;
228
+ onRevert: () => void;
229
+ largeControls?: boolean;
230
+ className?: string;
231
+ style?: CSSProperties;
232
+ }
233
+ declare function ProfilePreviewCard({ profile, isActive, onApply, onRevert, largeControls, className, style, }: ProfilePreviewCardProps): react.JSX.Element;
234
+
116
235
  interface AccessibilityState {
117
236
  isOpen: boolean;
118
237
  features: Record<string, unknown>;
@@ -242,4 +361,4 @@ declare function ReadingGuideController(): react.JSX.Element;
242
361
 
243
362
  declare function ResetController(): react.JSX.Element;
244
363
 
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 };
364
+ export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, type AccessibilityState, BigCursorController, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, type CursorSizePreference, DEFAULT_PREFERENCES, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, FeatureCard, type FeatureCardProps, type FeatureOptions, type FeatureRegistration, type FeatureStatus, type FontFamilyPreference, FontSizeController, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LetterSpacingController, LineHeightController, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, type PluginPosition, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, type ReaderMode, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, type SaturationPreference, SearchCount, type SearchCountProps, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TextAlignController, type TextAlignPreference, ToggleControl, type ToggleControlProps, type WidgetPlacement, createInitialPreferencesState, enLocale, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };
package/dist/index.d.ts CHANGED
@@ -113,6 +113,125 @@ declare function registerLocale(code: string, strings: LocaleStrings): void;
113
113
  declare function isRtlLocale(localeProp?: string): boolean;
114
114
  declare function resolveLocaleStrings(localeProp?: string): LocaleStrings;
115
115
 
116
+ interface ToggleControlProps {
117
+ id?: string;
118
+ label: ReactNode;
119
+ checked: boolean;
120
+ onChange: (checked: boolean) => void;
121
+ disabled?: boolean;
122
+ unavailable?: boolean;
123
+ unavailableReason?: string;
124
+ name?: string;
125
+ description?: string;
126
+ largeControls?: boolean;
127
+ className?: string;
128
+ style?: CSSProperties;
129
+ }
130
+ declare function ToggleControl({ id, label, checked, onChange, disabled, unavailable, unavailableReason, name, description, largeControls, className, style, }: ToggleControlProps): react.JSX.Element;
131
+
132
+ interface ChoiceOption<T extends string | number> {
133
+ label: string;
134
+ value: T;
135
+ description?: string;
136
+ disabled?: boolean;
137
+ badge?: string;
138
+ }
139
+ interface ChoiceGroup<T extends string | number> {
140
+ label: string;
141
+ options: ChoiceOption<T>[];
142
+ }
143
+ interface ChoiceControlProps<T extends string | number> {
144
+ id?: string;
145
+ label: string;
146
+ value: T;
147
+ options?: ChoiceOption<T>[];
148
+ groups?: ChoiceGroup<T>[];
149
+ onChange: (value: T) => void;
150
+ disabled?: boolean;
151
+ largeControls?: boolean;
152
+ className?: string;
153
+ style?: CSSProperties;
154
+ orientation?: "horizontal" | "vertical";
155
+ }
156
+ declare function ChoiceControl<T extends string | number>({ id, label, value, options, groups, onChange, disabled, largeControls, className, style, orientation, }: ChoiceControlProps<T>): react.JSX.Element;
157
+
158
+ interface StepperControlProps {
159
+ id?: string;
160
+ label: string;
161
+ value: number;
162
+ min: number;
163
+ max: number;
164
+ step: number;
165
+ unit?: string;
166
+ formatValue?: (val: number) => string;
167
+ onChange: (value: number) => void;
168
+ showSlider?: boolean;
169
+ disabled?: boolean;
170
+ largeControls?: boolean;
171
+ className?: string;
172
+ style?: CSSProperties;
173
+ }
174
+ declare function StepperControl({ id, label, value, min, max, step, unit, formatValue, onChange, showSlider, disabled, largeControls, className, style, }: StepperControlProps): react.JSX.Element;
175
+
176
+ type FeatureStatus = "idle" | "active" | "error" | "unavailable" | "permission-required";
177
+ interface FeatureCardProps {
178
+ id?: string;
179
+ featureKey?: string;
180
+ icon?: ReactNode;
181
+ title: ReactNode;
182
+ description?: ReactNode;
183
+ statusBadge?: string;
184
+ status?: FeatureStatus;
185
+ errorMessage?: string;
186
+ unavailableMessage?: string;
187
+ permissionMessage?: string;
188
+ onRequestPermission?: () => void;
189
+ children: ReactNode;
190
+ className?: string;
191
+ style?: CSSProperties;
192
+ largeControls?: boolean;
193
+ }
194
+ declare function FeatureCard({ id, featureKey, icon, title, description, statusBadge, status, errorMessage, unavailableMessage, permissionMessage, onRequestPermission, children, className, style, largeControls, }: FeatureCardProps): react.JSX.Element;
195
+
196
+ interface SearchCountProps {
197
+ totalCount: number;
198
+ matchedCount: number;
199
+ query?: string;
200
+ className?: string;
201
+ style?: CSSProperties;
202
+ }
203
+ declare function SearchCount({ totalCount, matchedCount, query, className, style, }: SearchCountProps): react.JSX.Element;
204
+ interface EmptyStateProps {
205
+ title?: string;
206
+ description?: string;
207
+ actionLabel?: string;
208
+ onAction?: () => void;
209
+ icon?: ReactNode;
210
+ className?: string;
211
+ style?: CSSProperties;
212
+ }
213
+ declare function EmptyState({ title, description, actionLabel, onAction, icon, className, style, }: EmptyStateProps): react.JSX.Element;
214
+ interface ErrorStateProps {
215
+ title?: string;
216
+ message: string;
217
+ onRetry?: () => void;
218
+ retryLabel?: string;
219
+ className?: string;
220
+ style?: CSSProperties;
221
+ }
222
+ declare function ErrorState({ title, message, onRetry, retryLabel, className, style, }: ErrorStateProps): react.JSX.Element;
223
+
224
+ interface ProfilePreviewCardProps {
225
+ profile: ProfileDefinition;
226
+ isActive: boolean;
227
+ onApply: (profile: ProfileDefinition) => void;
228
+ onRevert: () => void;
229
+ largeControls?: boolean;
230
+ className?: string;
231
+ style?: CSSProperties;
232
+ }
233
+ declare function ProfilePreviewCard({ profile, isActive, onApply, onRevert, largeControls, className, style, }: ProfilePreviewCardProps): react.JSX.Element;
234
+
116
235
  interface AccessibilityState {
117
236
  isOpen: boolean;
118
237
  features: Record<string, unknown>;
@@ -242,4 +361,4 @@ declare function ReadingGuideController(): react.JSX.Element;
242
361
 
243
362
  declare function ResetController(): react.JSX.Element;
244
363
 
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 };
364
+ export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, type AccessibilityState, BigCursorController, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, type CursorSizePreference, DEFAULT_PREFERENCES, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, FeatureCard, type FeatureCardProps, type FeatureOptions, type FeatureRegistration, type FeatureStatus, type FontFamilyPreference, FontSizeController, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LetterSpacingController, LineHeightController, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, type PluginPosition, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, type ReaderMode, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, type SaturationPreference, SearchCount, type SearchCountProps, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TextAlignController, type TextAlignPreference, ToggleControl, type ToggleControlProps, type WidgetPlacement, createInitialPreferencesState, enLocale, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };