@jmruthers/pace-core 0.5.117 → 0.5.119

package/src/components/DataTable/utils/__tests__/a11yUtils.test.ts

@@ -0,0 +1,612 @@
+/**
+ * @file Accessibility Utils Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils/__tests__
+ * @since 0.4.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  initializeLiveRegion,
+  cleanupLiveRegion,
+  announce,
+  getSortButtonLabel,
+  announceSortChange,
+  announceFilterChange,
+  announceSearchResults,
+  announcePaginationChange,
+  announceSelectionChange,
+  announceLoadingState,
+  announceBulkOperation,
+  getAriaSortValue,
+  getRowDescription,
+} from '../a11yUtils';
+
+describe('[unit] a11yUtils', () => {
+  beforeEach(() => {
+    // Clear any existing live region
+    if (document.body.querySelector('.sr-only[aria-live]')) {
+      const existing = document.body.querySelector('.sr-only[aria-live]');
+      if (existing) {
+        document.body.removeChild(existing);
+      }
+    }
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    cleanupLiveRegion();
+    vi.useRealTimers();
+    vi.clearAllMocks();
+  });
+
+  describe('initializeLiveRegion', () => {
+    it('creates live region element when none exists', () => {
+      const region = initializeLiveRegion();
+
+      expect(region).not.toBeNull();
+      expect(region).toBeInstanceOf(HTMLElement);
+      expect(region?.getAttribute('aria-live')).toBe('polite');
+      expect(region?.getAttribute('aria-atomic')).toBe('true');
+      expect(region?.getAttribute('class')).toBe('sr-only');
+      expect(region?.style.position).toBe('absolute');
+      expect(region?.style.left).toBe('-10000px');
+      expect(region?.style.width).toBe('1px');
+      expect(region?.style.height).toBe('1px');
+      expect(region?.style.overflow).toBe('hidden');
+      expect(document.body.contains(region!)).toBe(true);
+    });
+
+    it('returns existing live region if already created', () => {
+      const firstRegion = initializeLiveRegion();
+      const secondRegion = initializeLiveRegion();
+
+      expect(firstRegion).toBe(secondRegion);
+      expect(document.body.querySelectorAll('.sr-only[aria-live]')).toHaveLength(1);
+    });
+
+    it('creates new region if existing one is not in document', () => {
+      const firstRegion = initializeLiveRegion();
+      document.body.removeChild(firstRegion!);
+      
+      const secondRegion = initializeLiveRegion();
+      expect(secondRegion).not.toBe(firstRegion);
+      expect(document.body.contains(secondRegion!)).toBe(true);
+    });
+
+    it('returns null in SSR environment', () => {
+      const originalWindow = global.window;
+      // @ts-expect-error - Testing SSR scenario
+      delete global.window;
+
+      const region = initializeLiveRegion();
+      expect(region).toBeNull();
+
+      global.window = originalWindow;
+    });
+  });
+
+  describe('cleanupLiveRegion', () => {
+    it('removes live region from document', () => {
+      const region = initializeLiveRegion();
+      expect(document.body.contains(region!)).toBe(true);
+
+      cleanupLiveRegion();
+      expect(document.body.contains(region!)).toBe(false);
+    });
+
+    it('sets live region to null after cleanup', () => {
+      initializeLiveRegion();
+      cleanupLiveRegion();
+      
+      // Second call should not throw
+      cleanupLiveRegion();
+      expect(document.body.querySelector('.sr-only[aria-live]')).toBeNull();
+    });
+
+    it('handles cleanup when region does not exist', () => {
+      expect(() => cleanupLiveRegion()).not.toThrow();
+    });
+
+    it('handles cleanup when region is not in document', () => {
+      const region = initializeLiveRegion();
+      document.body.removeChild(region!);
+      
+      expect(() => cleanupLiveRegion()).not.toThrow();
+    });
+
+    it('returns early in SSR environment', () => {
+      const originalWindow = global.window;
+      // @ts-expect-error - Testing SSR scenario
+      delete global.window;
+
+      expect(() => cleanupLiveRegion()).not.toThrow();
+
+      global.window = originalWindow;
+    });
+  });
+
+  describe('announce', () => {
+    it('announces message with polite priority by default', () => {
+      initializeLiveRegion();
+      announce('Test message');
+
+      vi.advanceTimersByTime(100);
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.getAttribute('aria-live')).toBe('polite');
+      expect(region.textContent).toBe('Test message');
+    });
+
+    it('announces message with assertive priority', () => {
+      initializeLiveRegion();
+      announce('Urgent message', 'assertive');
+
+      vi.advanceTimersByTime(100);
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.getAttribute('aria-live')).toBe('assertive');
+      expect(region.textContent).toBe('Urgent message');
+    });
+
+    it('updates aria-live attribute when priority changes', () => {
+      initializeLiveRegion();
+      announce('First message', 'polite');
+      vi.advanceTimersByTime(100);
+
+      announce('Second message', 'assertive');
+      vi.advanceTimersByTime(100);
+      
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.getAttribute('aria-live')).toBe('assertive');
+    });
+
+    it('clears message after delay to avoid repetition', () => {
+      initializeLiveRegion();
+      announce('Test message');
+
+      vi.advanceTimersByTime(100);
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Test message');
+
+      vi.advanceTimersByTime(1000);
+      expect(region.textContent).toBe('');
+    });
+
+    it('does not clear message if content changed during delay', () => {
+      initializeLiveRegion();
+      announce('First message');
+      vi.advanceTimersByTime(100);
+      
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('First message');
+
+      // Announce new message before first timeout clears
+      announce('Second message');
+      vi.advanceTimersByTime(100);
+      expect(region.textContent).toBe('Second message');
+
+      // First timeout should not clear since content changed (it was 'Second message', not 'First message')
+      vi.advanceTimersByTime(900);
+      // The second timeout should clear it after 1000ms, but we need to advance past the first timeout
+      // The first timeout (1000ms after first announce) checks if textContent === 'First message'
+      // Since it's now 'Second message', it won't clear
+      // Then we advance to the second timeout (1000ms after second announce)
+      vi.advanceTimersByTime(100);
+      // Now the second timeout should check if textContent === 'Second message' and clear it
+      expect(region.textContent).toBe('');
+    });
+
+    it('does not announce empty or whitespace-only messages', () => {
+      initializeLiveRegion();
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      
+      announce('');
+      announce('   ');
+      announce('\n\t  ');
+      
+      vi.advanceTimersByTime(100);
+      expect(region.textContent).toBe('');
+    });
+
+    it('returns early in SSR environment', () => {
+      const originalWindow = global.window;
+      // @ts-expect-error - Testing SSR scenario
+      delete global.window;
+
+      expect(() => announce('Test message')).not.toThrow();
+
+      global.window = originalWindow;
+    });
+
+    it('initializes live region if not already initialized', () => {
+      announce('Auto-init message');
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region).not.toBeNull();
+      expect(region.textContent).toBe('Auto-init message');
+    });
+  });
+
+  describe('getSortButtonLabel', () => {
+    it('returns ascending label when no sort is applied', () => {
+      expect(getSortButtonLabel('Name', false)).toBe('Sort Name ascending');
+    });
+
+    it('returns descending label when ascending sort is applied', () => {
+      expect(getSortButtonLabel('Name', 'asc')).toBe('Sort Name descending');
+    });
+
+    it('returns remove sort label when descending sort is applied', () => {
+      expect(getSortButtonLabel('Name', 'desc')).toBe('Remove sort from Name');
+    });
+
+    it('handles column names with special characters', () => {
+      expect(getSortButtonLabel('User Name', false)).toBe('Sort User Name ascending');
+      expect(getSortButtonLabel('Email Address', 'asc')).toBe('Sort Email Address descending');
+    });
+  });
+
+  describe('announceSortChange', () => {
+    beforeEach(() => {
+      initializeLiveRegion();
+    });
+
+    it('announces ascending sort', () => {
+      announceSortChange('Name', 'asc');
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Table sorted by Name in ascending order');
+    });
+
+    it('announces descending sort', () => {
+      announceSortChange('Name', 'desc');
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Table sorted by Name in descending order');
+    });
+
+    it('announces sort removal', () => {
+      announceSortChange('Name', null);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Sort removed from Name');
+    });
+
+    it('handles column names with special characters', () => {
+      announceSortChange('Email Address', 'asc');
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Table sorted by Email Address in ascending order');
+    });
+  });
+
+  describe('announceFilterChange', () => {
+    beforeEach(() => {
+      initializeLiveRegion();
+    });
+
+    it('announces filter with single result', () => {
+      announceFilterChange('Name', 'John', 1);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Filtered Name by "John". 1 result found.');
+    });
+
+    it('announces filter with multiple results', () => {
+      announceFilterChange('Name', 'John', 5);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Filtered Name by "John". 5 results found.');
+    });
+
+    it('announces filter removal when filter value is empty', () => {
+      announceFilterChange('Name', '', 0);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Filter removed from Name');
+    });
+
+    it('announces filter removal when filter value is whitespace', () => {
+      announceFilterChange('Name', '   ', 0);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Filter removed from Name');
+    });
+
+    it('handles filter values with special characters', () => {
+      announceFilterChange('Email', 'test@example.com', 2);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Filtered Email by "test@example.com". 2 results found.');
+    });
+  });
+
+  describe('announceSearchResults', () => {
+    beforeEach(() => {
+      initializeLiveRegion();
+    });
+
+    it('announces search with single result', () => {
+      announceSearchResults('test', 1);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Search for "test" returned 1 result.');
+    });
+
+    it('announces search with multiple results', () => {
+      announceSearchResults('test', 10);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Search for "test" returned 10 results.');
+    });
+
+    it('announces search cleared when query is empty', () => {
+      announceSearchResults('', 0);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Search cleared');
+    });
+
+    it('announces search cleared when query is whitespace', () => {
+      announceSearchResults('   ', 0);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Search cleared');
+    });
+
+    it('handles search queries with special characters', () => {
+      announceSearchResults('test@example.com', 3);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Search for "test@example.com" returned 3 results.');
+    });
+  });
+
+  describe('announcePaginationChange', () => {
+    beforeEach(() => {
+      initializeLiveRegion();
+    });
+
+    it('announces first page', () => {
+      announcePaginationChange(1, 5, 10, 50);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Page 1 of 5. Showing items 1 to 10 of 50.');
+    });
+
+    it('announces middle page', () => {
+      announcePaginationChange(3, 5, 10, 50);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Page 3 of 5. Showing items 21 to 30 of 50.');
+    });
+
+    it('announces last page', () => {
+      announcePaginationChange(5, 5, 10, 50);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Page 5 of 5. Showing items 41 to 50 of 50.');
+    });
+
+    it('announces single page', () => {
+      announcePaginationChange(1, 1, 10, 5);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Page 1 of 1. Showing items 1 to 5 of 5.');
+    });
+
+    it('handles page where last item exceeds total', () => {
+      announcePaginationChange(2, 2, 10, 15);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Page 2 of 2. Showing items 11 to 15 of 15.');
+    });
+
+    it('handles edge case with single item', () => {
+      announcePaginationChange(1, 1, 1, 1);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Page 1 of 1. Showing items 1 to 1 of 1.');
+    });
+  });
+
+  describe('announceSelectionChange', () => {
+    beforeEach(() => {
+      initializeLiveRegion();
+    });
+
+    it('announces all rows deselected', () => {
+      announceSelectionChange(0, 10);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('All rows deselected');
+    });
+
+    it('announces all rows selected', () => {
+      announceSelectionChange(10, 10);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('All 10 rows selected');
+    });
+
+    it('announces partial selection', () => {
+      announceSelectionChange(5, 10);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('5 of 10 rows selected');
+    });
+
+    it('handles single row selection', () => {
+      announceSelectionChange(1, 1);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('All 1 rows selected');
+    });
+
+    it('handles large numbers', () => {
+      announceSelectionChange(500, 1000);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('500 of 1000 rows selected');
+    });
+  });
+
+  describe('announceLoadingState', () => {
+    beforeEach(() => {
+      initializeLiveRegion();
+    });
+
+    it('announces loading state', () => {
+      announceLoadingState(true, false);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Loading data...');
+    });
+
+    it('announces loaded state', () => {
+      announceLoadingState(false, false);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('Data loaded');
+    });
+
+    it('announces error state with assertive priority', () => {
+      announceLoadingState(false, true);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.getAttribute('aria-live')).toBe('assertive');
+      expect(region.textContent).toBe('Error loading data');
+    });
+
+    it('prioritizes error over loading state', () => {
+      announceLoadingState(true, true);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.getAttribute('aria-live')).toBe('assertive');
+      expect(region.textContent).toBe('Error loading data');
+    });
+  });
+
+  describe('announceBulkOperation', () => {
+    beforeEach(() => {
+      initializeLiveRegion();
+    });
+
+    it('announces bulk operation with single item', () => {
+      announceBulkOperation('delete', 1);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('delete completed for 1 item');
+    });
+
+    it('announces bulk operation with multiple items', () => {
+      announceBulkOperation('delete', 5);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('delete completed for 5 items');
+    });
+
+    it('handles different operation types', () => {
+      announceBulkOperation('export', 10);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('export completed for 10 items');
+    });
+
+    it('handles zero items', () => {
+      announceBulkOperation('delete', 0);
+      vi.advanceTimersByTime(100);
+
+      const region = document.body.querySelector('.sr-only[aria-live]') as HTMLElement;
+      expect(region.textContent).toBe('delete completed for 0 items');
+    });
+  });
+
+  describe('getAriaSortValue', () => {
+    it('returns ascending for asc sort', () => {
+      expect(getAriaSortValue('asc')).toBe('ascending');
+    });
+
+    it('returns descending for desc sort', () => {
+      expect(getAriaSortValue('desc')).toBe('descending');
+    });
+
+    it('returns none when no sort is applied', () => {
+      expect(getAriaSortValue(false)).toBe('none');
+    });
+  });
+
+  describe('getRowDescription', () => {
+    it('returns basic row description', () => {
+      expect(getRowDescription(0, 10)).toBe('Row 1 of 10');
+    });
+
+    it('returns description with selected state', () => {
+      expect(getRowDescription(0, 10, true)).toBe('Row 1 of 10, selected');
+    });
+
+    it('returns description with editing state', () => {
+      expect(getRowDescription(0, 10, false, true)).toBe('Row 1 of 10, editing mode');
+    });
+
+    it('returns description with both selected and editing states', () => {
+      expect(getRowDescription(0, 10, true, true)).toBe('Row 1 of 10, selected, editing mode');
+    });
+
+    it('handles middle row', () => {
+      expect(getRowDescription(5, 10)).toBe('Row 6 of 10');
+    });
+
+    it('handles last row', () => {
+      expect(getRowDescription(9, 10)).toBe('Row 10 of 10');
+    });
+
+    it('handles single row', () => {
+      expect(getRowDescription(0, 1)).toBe('Row 1 of 1');
+    });
+
+    it('handles large row counts', () => {
+      expect(getRowDescription(999, 1000)).toBe('Row 1000 of 1000');
+    });
+
+    it('handles zero-based index correctly', () => {
+      expect(getRowDescription(0, 5)).toBe('Row 1 of 5');
+      expect(getRowDescription(1, 5)).toBe('Row 2 of 5');
+      expect(getRowDescription(4, 5)).toBe('Row 5 of 5');
+    });
+  });
+});
+