@jmruthers/pace-core 0.5.76 → 0.5.77

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

@@ -0,0 +1,244 @@
+/**
+ * @file Accessibility Utilities for DataTable
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils
+ * @since 0.4.0
+ * 
+ * Utilities for managing accessibility features in DataTable components.
+ */
+
+/**
+ * Live region instance for screen reader announcements
+ */
+let liveRegion: HTMLElement | null = null;
+
+/**
+ * Initialize the live region for screen reader announcements
+ * This should be called once when the DataTable is mounted
+ */
+export function initializeLiveRegion(): HTMLElement | null {
+  if (typeof window === 'undefined') return null;
+  
+  if (liveRegion && document.contains(liveRegion)) {
+    return liveRegion;
+  }
+
+  // Create live region element
+  liveRegion = document.createElement('div');
+  liveRegion.setAttribute('aria-live', 'polite');
+  liveRegion.setAttribute('aria-atomic', 'true');
+  liveRegion.setAttribute('class', 'sr-only');
+  liveRegion.style.position = 'absolute';
+  liveRegion.style.left = '-10000px';
+  liveRegion.style.width = '1px';
+  liveRegion.style.height = '1px';
+  liveRegion.style.overflow = 'hidden';
+
+  // Add to document body
+  document.body.appendChild(liveRegion);
+
+  return liveRegion;
+}
+
+/**
+ * Clean up the live region when DataTable is unmounted
+ */
+export function cleanupLiveRegion(): void {
+  if (typeof window === 'undefined') return;
+  
+  if (liveRegion && document.contains(liveRegion)) {
+    document.body.removeChild(liveRegion);
+    liveRegion = null;
+  }
+}
+
+/**
+ * Announce a message to screen readers via the live region
+ * @param message - The message to announce
+ * @param priority - The priority level ('polite' or 'assertive')
+ */
+export function announce(message: string, priority: 'polite' | 'assertive' = 'polite'): void {
+  if (!message.trim() || typeof window === 'undefined') return;
+
+  const region = liveRegion || initializeLiveRegion();
+  if (!region) return;
+  
+  // Update aria-live attribute if needed
+  if (region.getAttribute('aria-live') !== priority) {
+    region.setAttribute('aria-live', priority);
+  }
+
+  // Clear and set the message
+  region.textContent = '';
+  
+  // Use setTimeout to ensure the screen reader picks up the change
+  setTimeout(() => {
+    region.textContent = message;
+  }, 100);
+
+  // Clear the message after a delay to avoid repetition
+  setTimeout(() => {
+    if (region.textContent === message) {
+      region.textContent = '';
+    }
+  }, 1000);
+}
+
+/**
+ * Generate accessible sort button label
+ * @param columnName - The name of the column
+ * @param currentSort - Current sort state ('asc', 'desc', or false)
+ */
+export function getSortButtonLabel(columnName: string, currentSort: 'asc' | 'desc' | false): string {
+  if (currentSort === 'asc') {
+    return `Sort ${columnName} descending`;
+  } else if (currentSort === 'desc') {
+    return `Remove sort from ${columnName}`;
+  } else {
+    return `Sort ${columnName} ascending`;
+  }
+}
+
+/**
+ * Generate accessible sort announcement
+ * @param columnName - The name of the column
+ * @param sortDirection - The new sort direction
+ */
+export function announceSortChange(columnName: string, sortDirection: 'asc' | 'desc' | null): void {
+  let message: string;
+  
+  if (sortDirection === 'asc') {
+    message = `Table sorted by ${columnName} in ascending order`;
+  } else if (sortDirection === 'desc') {
+    message = `Table sorted by ${columnName} in descending order`;
+  } else {
+    message = `Sort removed from ${columnName}`;
+  }
+  
+  announce(message);
+}
+
+/**
+ * Announce filter changes
+ * @param columnName - The name of the column being filtered
+ * @param filterValue - The filter value
+ * @param resultCount - Number of results after filtering
+ */
+export function announceFilterChange(columnName: string, filterValue: string, resultCount: number): void {
+  if (filterValue.trim()) {
+    const message = `Filtered ${columnName} by "${filterValue}". ${resultCount} ${resultCount === 1 ? 'result' : 'results'} found.`;
+    announce(message);
+  } else {
+    announce(`Filter removed from ${columnName}`);
+  }
+}
+
+/**
+ * Announce search results
+ * @param query - The search query
+ * @param resultCount - Number of search results
+ */
+export function announceSearchResults(query: string, resultCount: number): void {
+  if (query.trim()) {
+    const message = `Search for "${query}" returned ${resultCount} ${resultCount === 1 ? 'result' : 'results'}.`;
+    announce(message);
+  } else {
+    announce('Search cleared');
+  }
+}
+
+/**
+ * Announce pagination changes
+ * @param currentPage - Current page number (1-based)
+ * @param totalPages - Total number of pages
+ * @param pageSize - Number of items per page
+ * @param totalItems - Total number of items
+ */
+export function announcePaginationChange(
+  currentPage: number, 
+  totalPages: number, 
+  pageSize: number, 
+  totalItems: number
+): void {
+  const startItem = (currentPage - 1) * pageSize + 1;
+  const endItem = Math.min(currentPage * pageSize, totalItems);
+  
+  const message = `Page ${currentPage} of ${totalPages}. Showing items ${startItem} to ${endItem} of ${totalItems}.`;
+  announce(message);
+}
+
+/**
+ * Announce row selection changes
+ * @param selectedCount - Number of selected rows
+ * @param totalCount - Total number of rows
+ */
+export function announceSelectionChange(selectedCount: number, totalCount: number): void {
+  if (selectedCount === 0) {
+    announce('All rows deselected');
+  } else if (selectedCount === totalCount) {
+    announce(`All ${totalCount} rows selected`);
+  } else {
+    announce(`${selectedCount} of ${totalCount} rows selected`);
+  }
+}
+
+/**
+ * Announce data loading states
+ * @param isLoading - Whether data is currently loading
+ * @param hasError - Whether there was an error loading data
+ */
+export function announceLoadingState(isLoading: boolean, hasError: boolean = false): void {
+  if (hasError) {
+    announce('Error loading data', 'assertive');
+  } else if (isLoading) {
+    announce('Loading data...');
+  } else {
+    announce('Data loaded');
+  }
+}
+
+/**
+ * Announce bulk operations
+ * @param operation - The operation performed ('delete', 'export', etc.)
+ * @param count - Number of items affected
+ */
+export function announceBulkOperation(operation: string, count: number): void {
+  const message = `${operation} completed for ${count} ${count === 1 ? 'item' : 'items'}`;
+  announce(message);
+}
+
+/**
+ * Get ARIA sort value for column headers
+ * @param sortDirection - Current sort direction
+ */
+export function getAriaSortValue(sortDirection: 'asc' | 'desc' | false): 'ascending' | 'descending' | 'none' {
+  if (sortDirection === 'asc') return 'ascending';
+  if (sortDirection === 'desc') return 'descending';
+  return 'none';
+}
+
+/**
+ * Get accessible row description for screen readers
+ * @param rowIndex - The row index (0-based)
+ * @param totalRows - Total number of rows
+ * @param isSelected - Whether the row is selected
+ * @param isEditing - Whether the row is being edited
+ */
+export function getRowDescription(
+  rowIndex: number, 
+  totalRows: number, 
+  isSelected: boolean = false, 
+  isEditing: boolean = false
+): string {
+  let description = `Row ${rowIndex + 1} of ${totalRows}`;
+  
+  if (isSelected) {
+    description += ', selected';
+  }
+  
+  if (isEditing) {
+    description += ', editing mode';
+  }
+  
+  return description;
+}