accessibility-plugin-react 2.6.0 → 2.8.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,27 +88,27 @@ 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
- | `ParagraphSpacingController` | Applies 0–32px paragraph bottom margin spacing without altering table or code layouts. |
99
- | `ContrastController` | Turns contrast off, reduces it, increases it, or selects a named palette. |
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` | Hides images and CSS background images while retaining layout. |
107
- | `HideVideosController` | Hides video elements and recognized YouTube/Vimeo embeds visually. |
108
- | `BigCursorController` | Applies a larger high-contrast cursor where supported. |
109
- | `ReadingMaskController` | Dims the page around a transparent reading window. |
110
- | `ReadingGuideController` | Follows pointer/focus with a reading guide line. |
111
- | `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` | Hides images and CSS background images while retaining layout. |
107
+ | `HideVideosController` | Hides video elements and recognized YouTube/Vimeo embeds visually. |
108
+ | `BigCursorController` | Applies a larger high-contrast cursor where supported. |
109
+ | `ReadingMaskController` | Dims the page around a transparent reading window. |
110
+ | `ReadingGuideController` | Follows pointer/focus with a reading guide line. |
111
+ | `ResetController` | Resets display features and custom registered features without moving the widget. |
112
112
 
113
113
  Effects compose where appropriate. For example, contrast, saturation, invert,
114
114
  and grayscale are applied in a deterministic order. Defaults leave host styles
@@ -277,6 +277,9 @@ See [troubleshooting](docs/TROUBLESHOOTING.md) before filing an issue.
277
277
 
278
278
  - [API reference](docs/API.md)
279
279
  - [Feature behavior and bounds](docs/FEATURES.md)
280
+ - [Link highlighting, focus visibility, and landmark skip links](docs/LINKS_AND_FOCUS.md)
281
+ - [Contrast modes and forced-colors protection](docs/CONTRAST.md)
282
+ - [Legible and dyslexia font stacks](docs/FONTS.md)
280
283
  - [Installation and Next.js](docs/INSTALLATION.md)
281
284
  - [Content Security Policy (CSP) guidance](docs/CSP.md)
282
285
  - [Custom features](docs/CUSTOM_FEATURES.md)
package/dist/index.d.mts CHANGED
@@ -82,6 +82,7 @@ interface LocaleStrings {
82
82
  description: string;
83
83
  closeLabel: string;
84
84
  skipToActions: string;
85
+ skipToMain?: string;
85
86
  toolsLabel: string;
86
87
  quickActionsLabel: string;
87
88
  resetLabel: string;
@@ -326,6 +327,23 @@ declare function AccessibilityButton({ icon, draggable, title, description, clas
326
327
 
327
328
  declare function AccessibilityList(props: AccessibilityListProps): react.JSX.Element;
328
329
 
330
+ /**
331
+ * Searches the host document for an authentic main landmark:
332
+ * native `<main>` element or element with explicit `role="main"`.
333
+ * Returns null if no authentic main landmark exists.
334
+ */
335
+ declare function findMainLandmark(): HTMLElement | null;
336
+ interface SkipToMainLinkProps {
337
+ className?: string;
338
+ label?: string;
339
+ }
340
+ /**
341
+ * Accessible Skip to Main Content link.
342
+ * Only renders when a real `<main>` or `[role="main"]` landmark exists in the document,
343
+ * preventing broken or unreachable skip links in partial views or embedded layouts.
344
+ */
345
+ declare function SkipToMainLink({ className, label }: SkipToMainLinkProps): react.JSX.Element | null;
346
+
329
347
  declare function useAccessibility<T>(featureKey: string, defaultValue: T, options?: FeatureOptions<T>): {
330
348
  value: T;
331
349
  setValue: (next: T) => void;
@@ -374,7 +392,23 @@ declare const LINE_HEIGHT_RATIOS: readonly [1, 1.5, 1.75, 2];
374
392
  */
375
393
  declare const FONT_FAMILY_PRESETS: readonly ["default", "legible", "dyslexia-option"];
376
394
  type FontFamilyPreset = (typeof FONT_FAMILY_PRESETS)[number];
377
-
395
+ /**
396
+ * Semantic contrast modes: off/original (standard colors), light (crisp light), dark (deep dark), high (AAA high contrast), invert (luminance inversion).
397
+ */
398
+ declare const CONTRAST_MODES: readonly ["off", "original", "light", "dark", "high", "invert"];
399
+ type ContrastModeValue = (typeof CONTRAST_MODES)[number];
400
+
401
+ /** Detects whether the user's operating system has forced colors / high contrast active. */
402
+ declare function isForcedColorsActive(): boolean;
403
+ interface ContrastPalette {
404
+ text: string;
405
+ background: string;
406
+ border?: string;
407
+ link?: string;
408
+ }
409
+ declare const CONTRAST_PALETTES: Record<string, ContrastPalette>;
410
+ declare const CONTRAST_PROTECTED_SELECTOR: string;
411
+ declare function isProtectedFromContrast(element: HTMLElement): boolean;
378
412
  declare const TEXT_SCALE_PROTECTED_SELECTOR: string;
379
413
  declare function isProtectedFromTextScale(element: HTMLElement): boolean;
380
414
  declare const TEXT_SPACING_EXCLUDED_SELECTOR: string;
@@ -439,6 +473,8 @@ declare function ParagraphSpacingController({ min, max, step, steps, }?: Paragra
439
473
 
440
474
  declare function ContrastController(): react.JSX.Element;
441
475
 
476
+ declare function ContrastModeController(): react.JSX.Element;
477
+
442
478
  declare function SaturationController(): react.JSX.Element;
443
479
 
444
480
  declare function InvertColorsController(): react.JSX.Element;
@@ -461,6 +497,14 @@ declare function ReadingMaskController(): react.JSX.Element;
461
497
 
462
498
  declare function ReadingGuideController(): react.JSX.Element;
463
499
 
500
+ /**
501
+ * Controller to toggle enhanced focus visibility.
502
+ * Provides high-contrast, multi-layer focus outlines for keyboard navigation,
503
+ * preserving disabled states and yielding to native operating system high contrast themes.
504
+ */
505
+ declare function HighlightFocusController(): react.JSX.Element;
506
+ declare const FocusHighlightController: typeof HighlightFocusController;
507
+
464
508
  declare function ResetController(): react.JSX.Element;
465
509
 
466
- 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, 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, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PluginPosition, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, type ReaderMode, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, 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, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, createInitialPreferencesState, enLocale, getScriptSpacingConstraints, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };
510
+ export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, type AccessibilityState, BigCursorController, 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, 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, HideImagesController, HideVideosController, HighlightFocusController, InvertColorsController, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PluginPosition, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, type ReaderMode, ReadingGuideController, ReadingMaskController, 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, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, createInitialPreferencesState, enLocale, findMainLandmark, getScriptSpacingConstraints, isForcedColorsActive, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };
package/dist/index.d.ts CHANGED
@@ -82,6 +82,7 @@ interface LocaleStrings {
82
82
  description: string;
83
83
  closeLabel: string;
84
84
  skipToActions: string;
85
+ skipToMain?: string;
85
86
  toolsLabel: string;
86
87
  quickActionsLabel: string;
87
88
  resetLabel: string;
@@ -326,6 +327,23 @@ declare function AccessibilityButton({ icon, draggable, title, description, clas
326
327
 
327
328
  declare function AccessibilityList(props: AccessibilityListProps): react.JSX.Element;
328
329
 
330
+ /**
331
+ * Searches the host document for an authentic main landmark:
332
+ * native `<main>` element or element with explicit `role="main"`.
333
+ * Returns null if no authentic main landmark exists.
334
+ */
335
+ declare function findMainLandmark(): HTMLElement | null;
336
+ interface SkipToMainLinkProps {
337
+ className?: string;
338
+ label?: string;
339
+ }
340
+ /**
341
+ * Accessible Skip to Main Content link.
342
+ * Only renders when a real `<main>` or `[role="main"]` landmark exists in the document,
343
+ * preventing broken or unreachable skip links in partial views or embedded layouts.
344
+ */
345
+ declare function SkipToMainLink({ className, label }: SkipToMainLinkProps): react.JSX.Element | null;
346
+
329
347
  declare function useAccessibility<T>(featureKey: string, defaultValue: T, options?: FeatureOptions<T>): {
330
348
  value: T;
331
349
  setValue: (next: T) => void;
@@ -374,7 +392,23 @@ declare const LINE_HEIGHT_RATIOS: readonly [1, 1.5, 1.75, 2];
374
392
  */
375
393
  declare const FONT_FAMILY_PRESETS: readonly ["default", "legible", "dyslexia-option"];
376
394
  type FontFamilyPreset = (typeof FONT_FAMILY_PRESETS)[number];
377
-
395
+ /**
396
+ * Semantic contrast modes: off/original (standard colors), light (crisp light), dark (deep dark), high (AAA high contrast), invert (luminance inversion).
397
+ */
398
+ declare const CONTRAST_MODES: readonly ["off", "original", "light", "dark", "high", "invert"];
399
+ type ContrastModeValue = (typeof CONTRAST_MODES)[number];
400
+
401
+ /** Detects whether the user's operating system has forced colors / high contrast active. */
402
+ declare function isForcedColorsActive(): boolean;
403
+ interface ContrastPalette {
404
+ text: string;
405
+ background: string;
406
+ border?: string;
407
+ link?: string;
408
+ }
409
+ declare const CONTRAST_PALETTES: Record<string, ContrastPalette>;
410
+ declare const CONTRAST_PROTECTED_SELECTOR: string;
411
+ declare function isProtectedFromContrast(element: HTMLElement): boolean;
378
412
  declare const TEXT_SCALE_PROTECTED_SELECTOR: string;
379
413
  declare function isProtectedFromTextScale(element: HTMLElement): boolean;
380
414
  declare const TEXT_SPACING_EXCLUDED_SELECTOR: string;
@@ -439,6 +473,8 @@ declare function ParagraphSpacingController({ min, max, step, steps, }?: Paragra
439
473
 
440
474
  declare function ContrastController(): react.JSX.Element;
441
475
 
476
+ declare function ContrastModeController(): react.JSX.Element;
477
+
442
478
  declare function SaturationController(): react.JSX.Element;
443
479
 
444
480
  declare function InvertColorsController(): react.JSX.Element;
@@ -461,6 +497,14 @@ declare function ReadingMaskController(): react.JSX.Element;
461
497
 
462
498
  declare function ReadingGuideController(): react.JSX.Element;
463
499
 
500
+ /**
501
+ * Controller to toggle enhanced focus visibility.
502
+ * Provides high-contrast, multi-layer focus outlines for keyboard navigation,
503
+ * preserving disabled states and yielding to native operating system high contrast themes.
504
+ */
505
+ declare function HighlightFocusController(): react.JSX.Element;
506
+ declare const FocusHighlightController: typeof HighlightFocusController;
507
+
464
508
  declare function ResetController(): react.JSX.Element;
465
509
 
466
- 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, 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, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, HideImagesController, HideVideosController, InvertColorsController, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PluginPosition, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, type ReaderMode, ReadingGuideController, ReadingMaskController, ResetController, SaturationController, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, 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, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, createInitialPreferencesState, enLocale, getScriptSpacingConstraints, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };
510
+ export { AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, type AccessibilityState, BigCursorController, 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, 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, HideImagesController, HideVideosController, HighlightFocusController, InvertColorsController, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LocaleStrings, PROFILE_DEFINITIONS, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PluginPosition, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, type ReaderMode, ReadingGuideController, ReadingMaskController, 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, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, createInitialPreferencesState, enLocale, findMainLandmark, getScriptSpacingConstraints, isForcedColorsActive, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isRtlLocale, normalizePreferenceValue, normalizePreferences, preferencesReducer, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, useAccessibility };