Vision Accessibility

Универсальный компонент панели доступности для слабовидящих пользователей. Предоставляет настройки цветовой схемы, размера шрифта и отображения изображений.

Установка

npm install vision-accessibility

Использование

Базовое использование

import React, { useState } from 'react';
import { AccessibilityPanel } from 'vision-accessibility';
import 'vision-accessibility/dist/style.css'; // Импорт стилей

function App() {
  const [isAccessibilityPanelOpen, setIsAccessibilityPanelOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsAccessibilityPanelOpen(true)}>
        Настройки доступности
      </button>
      
      <AccessibilityPanel
        isOpen={isAccessibilityPanelOpen}
        onClose={() => setIsAccessibilityPanelOpen(false)}
        position="top-right"
      />
    </div>
  );
}

Импорт глобальных стилей

Для корректной работы высококонтрастной темы и скрытия изображений необходимо импортировать глобальные стили в ваш основной CSS файл:

// В вашем globals.scss или main.scss
@import 'vision-accessibility/dist/global.scss';

Или импортировать в JavaScript:

import 'vision-accessibility/dist/global.css';

Использование хуков

import { useAccessibilitySettings, useAccessibilityToggle } from 'vision-accessibility';

function MyComponent() {
  const { settings, updateSettings } = useAccessibilitySettings();
  const [isEnabled, setEnabled] = useAccessibilityToggle();

  return (
    <div>
      <p>Режим доступности: {isEnabled ? 'включен' : 'выключен'}</p>
      <p>Цветовая схема: {settings.colorScheme}</p>
      <p>Размер шрифта: {settings.fontSize}</p>
    </div>
  );
}

Использование контекста

import { AccessibilityProvider, useAccessibilityContext } from 'vision-accessibility';

function App() {
  return (
    <AccessibilityProvider>
      <MyComponent />
    </AccessibilityProvider>
  );
}

function MyComponent() {
  const { settings, updateSettings } = useAccessibilityContext();
  
  return (
    <button onClick={() => updateSettings({ fontSize: 'large' })}>
      Увеличить шрифт
    </button>
  );
}

API

AccessibilityPanel

Основной компонент панели доступности.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | isOpen | boolean | - | Открыта ли панель | | onClose | () => void | - | Обработчик закрытия панели | | position | 'top-right' \| 'top-left' | 'top-right' | Позиция панели | | translations | AccessibilityTranslations | - | Объект с переводами для локализации текста панели |

Translations

Компонент поддерживает локализацию текстовых строк через проп translations. Доступны следующие ключи:

interface AccessibilityTranslations {
  panelTitle?: string;                           // Заголовок панели ("Настройки доступности")
  panelDescription?: string;                     // Описание панели ("Настройте отображение страницы...")
  closePanelLabel?: string;                      // Текст для aria-label кнопки закрытия
  colorSchemeTitle?: string;                     // Заголовок секции цветовой схемы
  colorSchemeStandardLabel?: string;             // Значение опции стандартной цветовой схемы
  colorSchemeStandardDescription?: string;       // Описание опции стандартной цветовой схемы
  colorSchemeHighContrastLabel?: string;         // Значение опции высококонтрастной цветовой схемы
  colorSchemeHighContrastDescription?: string;   // Описание опции высококонтрастной цветовой схемы
  colorSchemeGrayscaleLabel?: string;            // Значение опции черно-белой цветовой схемы
  colorSchemeGrayscaleDescription?: string;      // Описание опции черно-белой цветовой схемы
  fontSizeTitle?: string;                        // Заголовок секции размера шрифта
  fontSizeSmallLabel?: string;                   // Значение опции маленького шрифта
  fontSizeSmallDescription?: string;             // Описание опции маленького шрифта
  fontSizeStandardLabel?: string;                // Значение опции стандартного шрифта
  fontSizeStandardDescription?: string;          // Описание опции стандартного шрифта
  fontSizeLargeLabel?: string;                   // Значение опции большого шрифта
  fontSizeLargeDescription?: string;              // Описание опции большого шрифта
  imageControlTitle?: string;                    // Заголовок секции изображений
  imageControlShowLabel?: string;                // Текст для переключателя показа изображений
  imageControlHideLabel?: string;                // Текст для переключателя скрытия изображений
  accessibilityToggleLabel?: string;             // Текст для переключателя доступности
  accessibilityEnableDescription?: string;       // Описание для включенного состояния переключателя
  accessibilityDisableDescription?: string;      // Описание для выключенного состояния переключателя
}

Пример использования:

<AccessibilityPanel
  isOpen={isAccessibilityPanelOpen}
  onClose={() => setIsAccessibilityPanelOpen(false)}
  position="top-right"
  translations={{
    panelTitle: "Accessibility Settings",
    panelDescription: "Adjust page display for better accessibility",
    closePanelLabel: "Close accessibility panel",
    colorSchemeTitle: "Color Scheme",
    colorSchemeStandardLabel: "Standard",
    colorSchemeStandardDescription: "Normal color scheme",
    colorSchemeHighContrastLabel: "High Contrast",
    colorSchemeHighContrastDescription: "High contrast for better readability",
    colorSchemeGrayscaleLabel: "Grayscale",
    colorSchemeGrayscaleDescription: "Convert all colors to grayscale",
    fontSizeTitle: "Font Size",
    fontSizeSmallLabel: "Small",
    fontSizeSmallDescription: "Reduced text size (80%)",
    fontSizeStandardLabel: "Standard",
    fontSizeStandardDescription: "Normal text size",
    fontSizeLargeLabel: "Large",
    fontSizeLargeDescription: "Increased text size (130%)",
    imageControlTitle: "Images",
    imageControlShowLabel: "Show Images",
    imageControlHideLabel: "Hide Images",
    accessibilityToggleLabel: "Accessibility mode",
    accessibilityEnableDescription: "All accessibility settings are active. Use controls below for fine-tuning.",
    accessibilityDisableDescription: "Enable accessibility mode to activate all settings. When disabled, all changes will be reset."
  }}
/>

Типы

export type ColorScheme = 'standard' | 'high-contrast' | 'grayscale';
export type FontSize = 'small' | 'standard' | 'large';

export interface AccessibilitySettings {
  isEnabled: boolean;
  colorScheme: ColorScheme;
  fontSize: FontSize;
  showImages: boolean;
}

Хуки

useAccessibilitySettings()

Основной хук для управления настройками доступности.

const { settings, updateSettings, resetSettings, isLoaded } = useAccessibilitySettings();

useAccessibilityToggle()

Хук для управления общим режимом доступности.

const [isEnabled, setEnabled] = useAccessibilityToggle();

useAccessibilitySetting(key)

Хук для управления конкретной настройкой.

const [fontSize, setFontSize] = useAccessibilitySetting('fontSize');

Утилиты

CSS Applier

import { 
  applyColorScheme, 
  applyFontSize, 
  applyImageVisibility,
  removeAllAccessibilityStyles 
} from 'vision-accessibility';

// Применить цветовую схему
applyColorScheme('high-contrast');

// Применить размер шрифта
applyFontSize('large');

// Управление изображениями
applyImageVisibility(false); // скрыть изображения

// Сбросить все стили
removeAllAccessibilityStyles();

Storage

import { saveToStorage, loadFromStorage, clearStorage } from 'vision-accessibility';

// Сохранить настройки
saveToStorage(settings);

// Загрузить настройки
const savedSettings = loadFromStorage();

// Очистить настройки
clearStorage();

Функции

Цветовые схемы

• standard: Стандартная цветовая схема сайта
• high-contrast: Высококонтрастная схема (белый текст на черном фоне)
• grayscale: Черно-белый режим (все цвета преобразуются в оттенки серого)

Размеры шрифта

• small: Уменьшенный размер (80% от оригинального)
• standard: Стандартный размер
• large: Увеличенный размер (130% от оригинального)

Управление изображениями

• Возможность скрытия всех изображений на странице
• Сохранение возможности восстановления без перезагрузки

Особенности

• SSR совместимость: Работает с Next.js и другими SSR фреймворками
• Автосохранение: Настройки автоматически сохраняются в localStorage
• Динамические элементы: Автоматически применяет настройки к новым элементам
• Доступность: Полная поддержка клавиатурной навигации и screen readers
• TypeScript: Полная типизация всех компонентов и функций
• Portal рендеринг: Панель рендерится на верхнем уровне DOM для избежания проблем с z-index и позиционированием

Требования

• React >= 16.8.0
• React DOM >= 16.8.0

Лицензия

MIT