accessibility-plugin-react 2.13.0 → 2.17.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
@@ -88,28 +88,31 @@ export function App() {
88
88
  Every controller is opt-in. Add only the controls that make sense for your
89
89
  site, and choose their order in JSX.
90
90
 
91
- | Controller | Effect |
92
- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
93
- | `TextScaleController` | Stepwise reflow-safe text enlargement (1.0x, 1.125x, 1.25x, 1.5x, 2.0x) protecting forms, code, and icons. |
94
- | `FontSizeController` | Scales eligible HTML text from 50% to 200%; supports continuous 10% steps or `stepScale` mode. |
95
- | `LineHeightController` | Scales computed line height (50%–200%, step 10); supports `stepPresets` (100%, 150%, 175%, 200%). |
96
- | `LetterSpacingController` | Applies 0–10px letter spacing with automatic cursive (Arabic/RTL) and Indic (Sinhala/Tamil) protection. |
97
- | `WordSpacingController` | Applies 0–10px word spacing while protecting tables, code, forms, and widget internals. |
98
- | `ContrastController` | Adjusts contrast levels, palettes, or semantic modes while preserving images, video, charts, and validation. |
99
- | `ContrastModeController` | Applies light, dark, high contrast, or media-safe invert tokens with native forced-colors protection. |
100
- | `SaturationController` | Reduces or increases saturation. |
101
- | `InvertColorsController` | Inverts eligible page content. |
102
- | `GrayscaleController` | Removes color while preserving the selected saturation value for later. |
103
- | `LinkHighlightController` | Highlights links or selects a link palette. |
104
- | `TextAlignController` | Scopes left, center, right, or justified alignment to text blocks; warns about justification. |
105
- | `FontFamilyController` | Applies clean system-ui or OpenDyslexic with Sinhala/Tamil fallbacks while protecting code and icons. |
106
- | `HideImagesController` / `HideDecorativeImagesController` | Hides only eligible decorative images while preserving controls, CAPTCHA, charts, maps, and informative graphics. |
107
- | `HideVideosController` | Hides video elements and recognized YouTube/Vimeo embeds visually. |
108
- | `BigCursorController` | Applies a 40px high-contrast SVG pointer; capability-aware (requires `(pointer: fine)`). |
109
- | `ReadingMaskController` | Adjustable transparent reading window (40–400px, default 100px); pointer-transparent; follows pointer, touch, and focus. |
110
- | `ReadingGuideController` | 4px pointer-transparent guide ruler; never blocks clicks/selection; follows pointer, touch, and focus. |
111
- | `TooltipsController` / `AccessibleTooltipsController` | Accessible tooltips for authored descriptions (`aria-description`, `aria-describedby`, `alt`, etc.) with WCAG 1.4.13. |
112
- | `ResetController` | Resets display features and custom registered features without moving the widget. |
91
+ | Controller | Effect |
92
+ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
93
+ | `TextScaleController` | Stepwise reflow-safe text enlargement (1.0x, 1.125x, 1.25x, 1.5x, 2.0x) protecting forms, code, and icons. |
94
+ | `FontSizeController` | Scales eligible HTML text from 50% to 200%; supports continuous 10% steps or `stepScale` mode. |
95
+ | `LineHeightController` | Scales computed line height (50%–200%, step 10); supports `stepPresets` (100%, 150%, 175%, 200%). |
96
+ | `LetterSpacingController` | Applies 0–10px letter spacing with automatic cursive (Arabic/RTL) and Indic (Sinhala/Tamil) protection. |
97
+ | `WordSpacingController` | Applies 0–10px word spacing while protecting tables, code, forms, and widget internals. |
98
+ | `ContrastController` | Adjusts contrast levels, palettes, or semantic modes while preserving images, video, charts, and validation. |
99
+ | `ContrastModeController` | Applies light, dark, high contrast, or media-safe invert tokens with native forced-colors protection. |
100
+ | `SaturationController` | Reduces or increases saturation. |
101
+ | `InvertColorsController` | Inverts eligible page content. |
102
+ | `GrayscaleController` | Removes color while preserving the selected saturation value for later. |
103
+ | `LinkHighlightController` | Highlights links or selects a link palette. |
104
+ | `TextAlignController` | Scopes left, center, right, or justified alignment to text blocks; warns about justification. |
105
+ | `FontFamilyController` | Applies clean system-ui or OpenDyslexic with Sinhala/Tamil fallbacks while protecting code and icons. |
106
+ | `HideImagesController` / `HideDecorativeImagesController` | Hides only eligible decorative images while preserving controls, CAPTCHA, charts, maps, and informative graphics. |
107
+ | `HideVideosController` | Hides video elements and recognized YouTube/Vimeo embeds visually. |
108
+ | `BigCursorController` | Applies a 40px high-contrast SVG pointer; capability-aware (requires `(pointer: fine)`). |
109
+ | `ReadingMaskController` | Adjustable transparent reading window (40–400px, default 100px); pointer-transparent; follows pointer, touch, and focus. |
110
+ | `ReadingGuideController` | 4px pointer-transparent guide ruler; never blocks clicks/selection; follows pointer, touch, and focus. |
111
+ | `TooltipsController` / `AccessibleTooltipsController` | Accessible tooltips for authored descriptions (`aria-description`, `aria-describedby`, `alt`, etc.) with WCAG 1.4.13. |
112
+ | `PageNavigatorController` / `HeadingsNavigatorController` | Explores real headings and landmarks, supports keyboard navigation, safe scroll/focus, and search filtering. |
113
+ | `ProfilesController` / `ProfileController` | Previews, applies, and reverts eight neutral presets (Motor, Blind, Color Blind, Dyslexia, etc.) with deterministic overrides. |
114
+ | `PresetsController` / `CustomPresetsController` | Saves named custom presets and handles versioned JSON import/export with privacy exclusions. |
115
+ | `ResetController` | Resets display features and custom registered features without moving the widget. |
113
116
 
114
117
  Effects compose where appropriate. For example, contrast, saturation, invert,
115
118
  and grayscale are applied in a deterministic order. Defaults leave host styles
@@ -280,6 +283,7 @@ See [troubleshooting](docs/TROUBLESHOOTING.md) before filing an issue.
280
283
  - [Feature behavior and bounds](docs/FEATURES.md)
281
284
  - [Link highlighting, focus visibility, and landmark skip links](docs/LINKS_AND_FOCUS.md)
282
285
  - [Reduce motion and media controls](docs/REDUCE_MOTION.md)
286
+ - [Internationalization and locale packs](docs/LOCALES.md)
283
287
  - [Contrast modes and forced-colors protection](docs/CONTRAST.md)
284
288
  - [Legible and dyslexia font stacks](docs/FONTS.md)
285
289
  - [Installation and Next.js](docs/INSTALLATION.md)
package/dist/index.d.mts CHANGED
@@ -38,6 +38,11 @@ interface ProfileDefinition {
38
38
  description: string;
39
39
  settings: Partial<AccessibilityPreferences>;
40
40
  }
41
+ interface ActiveProfileState {
42
+ profileId: ProfilePresetId;
43
+ baseSnapshot: Partial<AccessibilityPreferences>;
44
+ overrides: Partial<AccessibilityPreferences>;
45
+ }
41
46
  interface PreferencesState {
42
47
  /** Base preferences configured before any profile was selected. */
43
48
  base: AccessibilityPreferences;
@@ -68,6 +73,7 @@ type PreferencesAction = {
68
73
  };
69
74
 
70
75
  declare const DEFAULT_PREFERENCES: Readonly<AccessibilityPreferences>;
76
+ declare const ALL_PROFILE_IDS: readonly ProfilePresetId[];
71
77
  declare const PROFILE_DEFINITIONS: Record<ProfilePresetId, ProfileDefinition>;
72
78
 
73
79
  declare function normalizePreferenceValue<K extends keyof AccessibilityPreferences>(key: K, value: unknown): AccessibilityPreferences[K];
@@ -77,6 +83,25 @@ declare function resolveEffectivePreferences(base: AccessibilityPreferences, pro
77
83
  declare function createInitialPreferencesState(initial?: Partial<AccessibilityPreferences> | null): PreferencesState;
78
84
  declare function preferencesReducer(state: PreferencesState, action: PreferencesAction): PreferencesState;
79
85
 
86
+ interface FeatureLocaleLabels {
87
+ textScale?: string;
88
+ lineHeight?: string;
89
+ letterSpacing?: string;
90
+ wordSpacing?: string;
91
+ paragraphSpacing?: string;
92
+ textAlign?: string;
93
+ fontFamily?: string;
94
+ contrast?: string;
95
+ highlightLinks?: string;
96
+ focusOutline?: string;
97
+ reduceMotion?: string;
98
+ cursorGuide?: string;
99
+ headingsNavigator?: string;
100
+ profiles?: string;
101
+ presets?: string;
102
+ readingMode?: string;
103
+ [key: string]: string | undefined;
104
+ }
80
105
  interface LocaleStrings {
81
106
  title: string;
82
107
  description: string;
@@ -106,13 +131,32 @@ interface LocaleStrings {
106
131
  moveDown: string;
107
132
  moveRight: string;
108
133
  largeControlsLabel: string;
134
+ cornerNames?: Record<string, string>;
109
135
  formatPointPosition?: (x: number, y: number) => string;
110
136
  formatCornerPosition?: (corner: string) => string;
111
- }
112
- type SupportedLocale = "en" | string;
137
+ searchPlaceholder?: string;
138
+ searchClearLabel?: string;
139
+ formatSearchCount?: (matched: number, total: number, query?: string) => string;
140
+ emptySearchTitle?: string;
141
+ emptySearchDescription?: string;
142
+ clearSearchLabel?: string;
143
+ formatProfileApplied?: (profileName: string) => string;
144
+ formatProfileReverted?: () => string;
145
+ formatPresetSaved?: (presetName: string) => string;
146
+ formatPresetApplied?: (presetName: string) => string;
147
+ formatPresetDeleted?: (presetName: string) => string;
148
+ decreaseTextSize?: string;
149
+ increaseTextSize?: string;
150
+ features?: FeatureLocaleLabels;
151
+ }
152
+ type SupportedLocale = "en" | "en-US" | "en-GB" | "si" | "si-LK" | "ta" | "ta-LK" | string;
113
153
 
114
154
  declare const enLocale: Readonly<LocaleStrings>;
115
155
 
156
+ declare const siLocale: Readonly<LocaleStrings>;
157
+
158
+ declare const taLocale: Readonly<LocaleStrings>;
159
+
116
160
  declare function registerLocale(code: string, strings: LocaleStrings): void;
117
161
  declare function isRtlLocale(localeProp?: string): boolean;
118
162
  declare function resolveLocaleStrings(localeProp?: string): LocaleStrings;
@@ -203,8 +247,9 @@ interface SearchCountProps {
203
247
  query?: string;
204
248
  className?: string;
205
249
  style?: CSSProperties;
250
+ locale?: string;
206
251
  }
207
- declare function SearchCount({ totalCount, matchedCount, query, className, style, }: SearchCountProps): react.JSX.Element;
252
+ declare function SearchCount({ totalCount, matchedCount, query, className, style, locale, }: SearchCountProps): react.JSX.Element;
208
253
  interface EmptyStateProps {
209
254
  title?: string;
210
255
  description?: string;
@@ -213,8 +258,9 @@ interface EmptyStateProps {
213
258
  icon?: ReactNode;
214
259
  className?: string;
215
260
  style?: CSSProperties;
261
+ locale?: string;
216
262
  }
217
- declare function EmptyState({ title, description, actionLabel, onAction, icon, className, style, }: EmptyStateProps): react.JSX.Element;
263
+ declare function EmptyState({ title, description, actionLabel, onAction, icon, className, style, locale, }: EmptyStateProps): react.JSX.Element;
218
264
  interface ErrorStateProps {
219
265
  title?: string;
220
266
  message: string;
@@ -352,6 +398,55 @@ declare function useAccessibility<T>(featureKey: string, defaultValue: T, option
352
398
 
353
399
  declare const AccessibilityContext: react.Context<AccessibilityContextValue | null>;
354
400
 
401
+ /**
402
+ * Retrieves a profile definition by its unique identifier.
403
+ */
404
+ declare function getProfileDefinition(id: ProfilePresetId): ProfileDefinition | undefined;
405
+ /**
406
+ * Maps typed AccessibilityPreferences settings to internal widget feature store keys.
407
+ */
408
+ declare function mapProfileSettingsToFeatures(settings: Partial<AccessibilityPreferences>): Record<string, unknown>;
409
+ /**
410
+ * Maps current live features from the store to typed AccessibilityPreferences.
411
+ */
412
+ declare function mapFeaturesToProfileSettings(features: Record<string, unknown>): Partial<AccessibilityPreferences>;
413
+ /**
414
+ * Atomically applies a profile to the live feature store.
415
+ * Preserves initial base settings in baseSnapshot and initializes empty overrides.
416
+ */
417
+ declare function applyProfileToStore(profileId: ProfilePresetId, currentFeatures: Record<string, unknown>, setFeatureState: <T>(key: string, value: T) => void, existingActiveState?: ActiveProfileState | null): ActiveProfileState;
418
+ /**
419
+ * Reverts an active profile back to custom settings with deterministic override survival.
420
+ * Settings that the user explicitly changed while the profile was active survive at their
421
+ * overridden values; settings untouched by the user revert to their pre-profile base values.
422
+ */
423
+ declare function revertProfileFromStore(activeProfileState: ActiveProfileState, setFeatureState: <T>(key: string, value: T) => void): void;
424
+ /**
425
+ * Records an explicit user override when a setting is modified while a profile is active.
426
+ */
427
+ declare function recordProfileOverride(key: keyof AccessibilityPreferences, value: AccessibilityPreferences[keyof AccessibilityPreferences], activeProfileState: ActiveProfileState | null, setFeatureState: <T>(key: string, value: T) => void): ActiveProfileState | null;
428
+
429
+ interface UseProfilesResult {
430
+ /** All eight predefined accessibility profiles in recommended order. */
431
+ profiles: readonly ProfileDefinition[];
432
+ /** Active profile preset ID or null if none is applied. */
433
+ activeProfileId: ProfilePresetId | null;
434
+ /** Active profile definition or null if none is applied. */
435
+ activeProfile: ProfileDefinition | null;
436
+ /** Complete active profile state including base snapshot and user overrides. */
437
+ activeProfileState: ActiveProfileState | null;
438
+ /** Atomically applies a profile to the store, preserving previous custom settings. */
439
+ applyProfile: (profileId: ProfilePresetId) => void;
440
+ /** Reverts the active profile, retaining any user explicit overrides. */
441
+ revertProfile: () => void;
442
+ /** Returns whether a specific profile preset is currently active. */
443
+ isProfileActive: (profileId: ProfilePresetId) => boolean;
444
+ }
445
+ /**
446
+ * Hook to access and manage accessibility profiles with deterministic override survival.
447
+ */
448
+ declare function useProfiles(): UseProfilesResult;
449
+
355
450
  interface FontSizeControllerProps {
356
451
  /**
357
452
  * Optional custom scale steps (percentages or factors, e.g. [100, 112.5, 125, 150, 200] or [1.0, 1.125, 1.25, 1.5, 2.0]).
@@ -371,7 +466,7 @@ interface TextScaleControllerProps {
371
466
  */
372
467
  steps?: readonly number[];
373
468
  /**
374
- * Accessible group label and visible title. Default: "Bigger Text".
469
+ * Accessible group label and visible title. Default: "Bigger Text" (or localized).
375
470
  */
376
471
  label?: string;
377
472
  }
@@ -572,6 +667,174 @@ interface TooltipsControllerProps {
572
667
  declare function TooltipsController({ className, label, description, }: TooltipsControllerProps): react.JSX.Element;
573
668
  declare const AccessibleTooltipsController: typeof TooltipsController;
574
669
 
670
+ interface PageNavigatorControllerProps {
671
+ className?: string;
672
+ label?: string;
673
+ description?: string;
674
+ closeOnNavigate?: boolean;
675
+ }
676
+ /**
677
+ * Controller to explore and navigate the page's semantic outline (Headings H1-H6 and Landmarks).
678
+ * Safely transfers focus and scrolls to elements with temporary tabindex cleanup.
679
+ * Truthfully displays empty states when pages lack headings or landmarks.
680
+ * Automatically synchronizes with dynamic DOM / SPA route changes without observer loops.
681
+ */
682
+ declare function PageNavigatorController({ className, label, description, closeOnNavigate, }: PageNavigatorControllerProps): react.JSX.Element;
683
+ declare const HeadingsNavigatorController: typeof PageNavigatorController;
684
+ declare const PageStructureController: typeof PageNavigatorController;
685
+
686
+ interface HeadingItem {
687
+ id: string;
688
+ level: number;
689
+ text: string;
690
+ element: HTMLElement;
691
+ }
692
+ interface LandmarkItem {
693
+ id: string;
694
+ type: string;
695
+ label: string;
696
+ element: HTMLElement;
697
+ }
698
+ /**
699
+ * Discovers all visible headings (h1-h6 or role="heading") in true DOM tree order,
700
+ * strictly excluding elements within the plugin UI.
701
+ */
702
+ declare function scanHeadings(root?: Document | Element): HeadingItem[];
703
+ /**
704
+ * Discovers all visible landmarks and named navigation anchors in true DOM tree order,
705
+ * strictly excluding elements within the plugin UI.
706
+ */
707
+ declare function scanLandmarks(root?: Document | Element): LandmarkItem[];
708
+ /**
709
+ * Safely scrolls to and focuses a target element.
710
+ * If the element is not naturally focusable, assigns a temporary tabindex="-1"
711
+ * and cleans it up on blur, preventing permanent mutation of host DOM semantics.
712
+ */
713
+ declare function navigateToElement(element: HTMLElement, options?: {
714
+ behavior?: ScrollBehavior;
715
+ onComplete?: () => void;
716
+ }): void;
717
+ /**
718
+ * Subscribes to DOM tree mutations outside the plugin UI without observer loops,
719
+ * refreshing headings/landmarks on dynamic client-side SPA route transitions.
720
+ */
721
+ declare function subscribePageStructure(callback: () => void): () => void;
722
+
723
+ interface ProfilesControllerProps {
724
+ className?: string;
725
+ label?: string;
726
+ description?: string;
727
+ largeControls?: boolean;
728
+ onProfileChange?: (profileId: ProfilePresetId | null) => void;
729
+ }
730
+ /**
731
+ * Controller to preview, apply, and revert eight neutral accessibility profile suggestions.
732
+ * Follows a deterministic override model where user explicit choices survive profile reversal.
733
+ * Guaranteed zero implicit audio, speech synthesis, or microphone activation.
734
+ */
735
+ declare function ProfilesController({ className, label, description, largeControls, onProfileChange, }: ProfilesControllerProps): react.JSX.Element;
736
+ declare const ProfileController: typeof ProfilesController;
737
+ declare const AccessibilityProfilesController: typeof ProfilesController;
738
+
575
739
  declare function ResetController(): react.JSX.Element;
576
740
 
577
- export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, type AccessibilityState, AccessibleTooltipsController, BigCursorController, type BigCursorControllerProps, CONTRAST_MODES, CONTRAST_PALETTES, CONTRAST_PROTECTED_SELECTOR, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, ContrastModeController, type ContrastModeValue, type ContrastPalette, type CursorSizePreference, DEFAULT_PREFERENCES, DEFAULT_READING_MASK_HEIGHT, DYSLEXIA_FONT_STACK, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, FONT_FAMILY_PRESETS, FONT_FAMILY_PROTECTED_SELECTOR, FeatureCard, type FeatureCardProps, type FeatureOptions, type FeatureRegistration, type FeatureStatus, FocusHighlightController, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, HideDecorativeImagesController, HideImagesController, type HideImagesControllerProps, HideVideosController, HighlightFocusController, InvertColorsController, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LocaleStrings, MAX_READING_MASK_HEIGHT, MIN_READING_MASK_HEIGHT, PROFILE_DEFINITIONS, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PluginPosition, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, READING_MASK_HEIGHT_PRESETS, type ReaderMode, ReadingGuideController, type ReadingGuideControllerProps, ReadingMaskController, type ReadingMaskControllerProps, ReduceMotionController, ResetController, SaturationController, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, SkipToMainLink, type SkipToMainLinkProps, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TEXT_ALIGN_BLOCK_SELECTOR, TEXT_SCALE_PROTECTED_SELECTOR, TEXT_SCALE_STEPS, TEXT_SPACING_EXCLUDED_SELECTOR, TextAlignController, type TextAlignPreference, TextScaleController, type TextScaleControllerProps, type TextScaleStep, ToggleControl, type ToggleControlProps, TooltipsController, type TooltipsControllerProps, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, createInitialPreferencesState, enLocale, enableAccessibleTooltips, findMainLandmark, getAuthoredDescription, getScriptSpacingConstraints, hasFinePointer, isEligibleDecorativeImage, isForcedColorsActive, isFunctionalOrMeaningfulImage, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isReducedMotionActive, isRtlLocale, normalizePreferenceValue, normalizePreferences, nudgeReadingAid, positionTooltip, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, subscribeFinePointer, subscribeForcedColors, subscribeReducedMotion, useAccessibility };
741
+ interface PresetsControllerProps {
742
+ className?: string;
743
+ label?: string;
744
+ description?: string;
745
+ largeControls?: boolean;
746
+ }
747
+ declare function PresetsController({ className, label, description, largeControls, }?: PresetsControllerProps): react.JSX.Element;
748
+ declare const CustomPresetsController: typeof PresetsController;
749
+ declare const SettingsImportExportController: typeof PresetsController;
750
+ declare const PresetsBackupController: typeof PresetsController;
751
+
752
+ interface CustomPreset {
753
+ id: string;
754
+ name: string;
755
+ createdAt: string;
756
+ updatedAt?: string;
757
+ settings: Partial<AccessibilityPreferences>;
758
+ }
759
+ interface PresetsExportV1 {
760
+ $schema?: string;
761
+ version: 1;
762
+ app: "accessibility-plugin-react";
763
+ exportedAt: string;
764
+ currentSettings?: Partial<AccessibilityPreferences>;
765
+ presets: CustomPreset[];
766
+ }
767
+ type ImportResult = {
768
+ success: true;
769
+ presets: CustomPreset[];
770
+ currentSettings?: Partial<AccessibilityPreferences>;
771
+ message: string;
772
+ } | {
773
+ success: false;
774
+ error: string;
775
+ };
776
+ /**
777
+ * List of allowed preference keys for privacy-safe storage and export.
778
+ * Strictly excludes any private user data, page text, transcripts, credentials, or session metadata.
779
+ */
780
+ declare const ALLOWED_PREFERENCE_KEYS: readonly ["fontScale", "lineHeight", "letterSpacingEm", "wordSpacingEm", "paragraphSpacingEm", "textAlign", "contrastMode", "highlightLinks", "highlightFocus", "reduceMotion", "hideDecorativeImages", "fontFamily", "cursorSize", "readerMode", "saturation", "tooltips"];
781
+ /**
782
+ * Sanitizes and extracts only valid, privacy-safe accessibility preferences.
783
+ * Discards any private, unknown, or extraneous fields.
784
+ */
785
+ declare function sanitizePreferences(raw: unknown): Partial<AccessibilityPreferences>;
786
+ /**
787
+ * Creates a validated, privacy-safe CustomPreset.
788
+ */
789
+ declare function createCustomPreset(name: string, settings: Partial<AccessibilityPreferences>): CustomPreset;
790
+ /**
791
+ * Validates a single CustomPreset object.
792
+ */
793
+ declare function isValidCustomPreset(item: unknown): item is CustomPreset;
794
+ /**
795
+ * Serializes custom presets and optional current settings into a versioned JSON string.
796
+ */
797
+ declare function exportPresetsToJson(options: {
798
+ presets: CustomPreset[];
799
+ currentSettings?: Partial<AccessibilityPreferences>;
800
+ }): string;
801
+ /**
802
+ * Triggers a browser download of the exported JSON file.
803
+ */
804
+ declare function downloadJsonFile(filename: string, jsonContent: string): void;
805
+ /**
806
+ * Validates and parses an imported JSON string into custom presets and settings.
807
+ * Handles valid v1 envelopes, legacy arrays of presets, legacy flat settings, and returns clear errors on malformed data.
808
+ */
809
+ declare function validateAndParseImport(jsonString: string): ImportResult;
810
+ /**
811
+ * Applies a custom preset's settings to the store.
812
+ */
813
+ declare function applyCustomPresetToStore(preset: CustomPreset, setFeatureState: <T>(key: string, value: T) => void): void;
814
+
815
+ interface UsePresetsResult {
816
+ /** List of all saved user presets. */
817
+ presets: CustomPreset[];
818
+ /** Current active settings mapped to AccessibilityPreferences. */
819
+ currentSettings: Partial<AccessibilityPreferences>;
820
+ /** Saves current configuration as a new named preset. */
821
+ saveCurrentAsPreset: (name: string) => CustomPreset;
822
+ /** Applies a preset by its unique ID. Returns true if found and applied. */
823
+ applyPreset: (presetId: string) => boolean;
824
+ /** Deletes a preset by its unique ID. Returns true if deleted. */
825
+ deletePreset: (presetId: string) => boolean;
826
+ /** Generates a version 1 JSON export of presets and optionally current settings. */
827
+ exportPresets: () => string;
828
+ /** Downloads the exported JSON file to the user's computer. */
829
+ downloadExport: (filename?: string) => void;
830
+ /** Validates and imports presets and settings from a JSON string. */
831
+ importFromJson: (jsonStr: string) => ImportResult;
832
+ /** Reads a File object and imports presets and settings. */
833
+ importFromFile: (file: File) => Promise<ImportResult>;
834
+ }
835
+ /**
836
+ * Hook to manage custom presets and versioned JSON settings import/export.
837
+ */
838
+ declare function usePresets(): UsePresetsResult;
839
+
840
+ export { ALLOWED_PREFERENCE_KEYS, ALL_PROFILE_IDS, AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, AccessibilityProfilesController, type AccessibilityState, AccessibleTooltipsController, type ActiveProfileState, BigCursorController, type BigCursorControllerProps, CONTRAST_MODES, CONTRAST_PALETTES, CONTRAST_PROTECTED_SELECTOR, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, ContrastModeController, type ContrastModeValue, type ContrastPalette, type CursorSizePreference, type CustomPreset, CustomPresetsController, DEFAULT_PREFERENCES, DEFAULT_READING_MASK_HEIGHT, DYSLEXIA_FONT_STACK, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, FONT_FAMILY_PRESETS, FONT_FAMILY_PROTECTED_SELECTOR, FeatureCard, type FeatureCardProps, type FeatureLocaleLabels, type FeatureOptions, type FeatureRegistration, type FeatureStatus, FocusHighlightController, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, type HeadingItem, HeadingsNavigatorController, HideDecorativeImagesController, HideImagesController, type HideImagesControllerProps, HideVideosController, HighlightFocusController, type ImportResult, InvertColorsController, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, type LandmarkItem, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LocaleStrings, MAX_READING_MASK_HEIGHT, MIN_READING_MASK_HEIGHT, PROFILE_DEFINITIONS, PageNavigatorController, type PageNavigatorControllerProps, PageStructureController, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PluginPosition, PresetsBackupController, PresetsController, type PresetsControllerProps, type PresetsExportV1, ProfileController, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, ProfilesController, type ProfilesControllerProps, READING_MASK_HEIGHT_PRESETS, type ReaderMode, ReadingGuideController, type ReadingGuideControllerProps, ReadingMaskController, type ReadingMaskControllerProps, ReduceMotionController, ResetController, SaturationController, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, SettingsImportExportController, SkipToMainLink, type SkipToMainLinkProps, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TEXT_ALIGN_BLOCK_SELECTOR, TEXT_SCALE_PROTECTED_SELECTOR, TEXT_SCALE_STEPS, TEXT_SPACING_EXCLUDED_SELECTOR, TextAlignController, type TextAlignPreference, TextScaleController, type TextScaleControllerProps, type TextScaleStep, ToggleControl, type ToggleControlProps, TooltipsController, type TooltipsControllerProps, type UsePresetsResult, type UseProfilesResult, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, applyCustomPresetToStore, applyProfileToStore, createCustomPreset, createInitialPreferencesState, downloadJsonFile, enLocale, enableAccessibleTooltips, exportPresetsToJson, findMainLandmark, getAuthoredDescription, getProfileDefinition, getScriptSpacingConstraints, hasFinePointer, isEligibleDecorativeImage, isForcedColorsActive, isFunctionalOrMeaningfulImage, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isReducedMotionActive, isRtlLocale, isValidCustomPreset, mapFeaturesToProfileSettings, mapProfileSettingsToFeatures, navigateToElement, normalizePreferenceValue, normalizePreferences, nudgeReadingAid, positionTooltip, preferencesReducer, recordProfileOverride, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, revertProfileFromStore, sanitizePreferences, scanHeadings, scanLandmarks, siLocale, subscribeFinePointer, subscribeForcedColors, subscribePageStructure, subscribeReducedMotion, taLocale, useAccessibility, usePresets, useProfiles, validateAndParseImport };