Web accessibilitybest practices 2025:creating inclusivedigital experiences

// React hook for comprehensive focus management
import { useEffect, useRef, useCallback } from 'react';

export const useFocusManagement = (isOpen: boolean) => {
  const containerRef = useRef<HTMLDivElement>(null);
  const previousFocusRef = useRef<HTMLElement | null>(null);

  // Store the previously focused element
  useEffect(() => {
    if (isOpen) {
      previousFocusRef.current = document.activeElement as HTMLElement;
    }
  }, [isOpen]);

  // Focus trap implementation
  const handleKeyDown = useCallback((event: KeyboardEvent) => {
    if (!isOpen || event.key !== 'Tab') return;

    const container = containerRef.current;
    if (!container) return;

    const focusableElements = container.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    
    const firstElement = focusableElements[0] as HTMLElement;
    const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;

    if (event.shiftKey) {
      if (document.activeElement === firstElement) {
        event.preventDefault();
        lastElement.focus();
      }
    } else {
      if (document.activeElement === lastElement) {
        event.preventDefault();
        firstElement.focus();
      }
    }
  }, [isOpen]);

  // Setup and cleanup focus management
  useEffect(() => {
    if (isOpen) {
      document.addEventListener('keydown', handleKeyDown);
      
      // Focus first focusable element
      const container = containerRef.current;
      if (container) {
        const firstFocusable = container.querySelector(
          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
        ) as HTMLElement;
        firstFocusable?.focus();
      }
    }

    return () => {
      document.removeEventListener('keydown', handleKeyDown);
      
      // Restore previous focus
      if (!isOpen && previousFocusRef.current) {
        previousFocusRef.current.focus();
      }
    };
  }, [isOpen, handleKeyDown]);

  // Handle escape key
  useEffect(() => {
    const handleEscape = (event: KeyboardEvent) => {
      if (event.key === 'Escape' && isOpen) {
        // Trigger close callback
        if (previousFocusRef.current) {
          previousFocusRef.current.focus();
        }
      }
    };

    if (isOpen) {
      document.addEventListener('keydown', handleEscape);
    }

    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen]);

  return containerRef;
};

// Accessible modal component
interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

export const AccessibleModal: React.FC<ModalProps> = ({
  isOpen,
  onClose,
  title,
  children
}) => {
  const containerRef = useFocusManagement(isOpen);

  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      className="fixed inset-0 z-50 bg-black bg-opacity-50"
      onClick={(e) => e.target === e.currentTarget && onClose()}
    >
      <div
        ref={containerRef}
        className="flex items-center justify-center min-h-screen p-4"
      >
        <div className="bg-white rounded-lg p-6 max-w-md w-full">
          <h2 id="modal-title" className="text-xl font-bold mb-4">
            {title}
          </h2>
          {children}
          <button
            onClick={onClose}
            className="mt-4 px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500"
          >
            Close
          </button>
        </div>
      </div>
    </div>
  );
};

// Jest + axe-core accessibility testing
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
import { AccessibleModal } from './AccessibleModal';

expect.extend(toHaveNoViolations);

describe('AccessibleModal', () => {
  test('should not have accessibility violations', async () => {
    const { container } = render(
      <AccessibleModal isOpen={true} onClose={() => {}} title="Test Modal">
        <p>Modal content</p>
      </AccessibleModal>
    );
    
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  test('should handle keyboard navigation', () => {
    const onClose = jest.fn();
    const { getByRole } = render(
      <AccessibleModal isOpen={true} onClose={onClose} title="Test Modal">
        <button>First Button</button>
        <button>Second Button</button>
      </AccessibleModal>
    );

    const modal = getByRole('dialog');
    expect(modal).toHaveAttribute('aria-modal', 'true');
    expect(modal).toHaveAttribute('aria-labelledby', 'modal-title');
  });
});

// Cypress accessibility testing
describe('Accessibility Tests', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe(); // Add axe-core to the page
  });

  it('should not have accessibility violations on homepage', () => {
    cy.checkA11y(); // Run accessibility audit
  });

  it('should be keyboard navigable', () => {
    // Test keyboard navigation
    cy.get('body').tab();
    cy.focused().should('have.class', 'skip-link');
    
    cy.get('body').tab();
    cy.focused().should('contain', 'Home');
    
    cy.get('body').tab();
    cy.focused().should('contain', 'About');
  });

  it('should work with screen reader', () => {
    // Test screen reader announcements
    cy.get('[role="main"]').should('exist');
    cy.get('h1').should('have.attr', 'aria-level', '1');
  });
});

// Performance monitoring for accessibility
class A11yMetrics {
  static trackKeyboardUsage(): void {
    let keyboardNavigation = false;
    
    document.addEventListener('keydown', (e) => {
      if (e.key === 'Tab') {
        keyboardNavigation = true;
        this.sendMetric('keyboard_navigation', 1);
      }
    });

    document.addEventListener('click', () => {
      if (!keyboardNavigation) {
        this.sendMetric('mouse_navigation', 1);
      }
    });
  }

  static trackFocusVisibility(): void {
    const observer = new MutationObserver((mutations) => {
      mutations.forEach((mutation) => {
        if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
          const target = mutation.target as HTMLElement;
          if (target.matches(':focus-visible')) {
            this.sendMetric('focus_visible', 1);
          }
        }
      });
    });

    observer.observe(document.body, {
      attributes: true,
      subtree: true
    });
  }

  private static sendMetric(name: string, value: number): void {
    navigator.sendBeacon('/analytics/a11y', JSON.stringify({
      metric: name,
      value,
      timestamp: Date.now(),
      userAgent: navigator.userAgent
    }));
  }
}