@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/components/DataTable/ui/toolbar/GroupingDropdown.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import { Button } from '../../../Button/Button';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+} from '../../../Select/Select';
+import { Group } from 'lucide-react';
+import type { DataTableColumn, DataRecord, SimpleColumn } from '../../types';
+
+/**
+ * Props for the GroupingDropdown component.
+ * @template TData - The type of data records in the table
+ */
+interface GroupingDropdownProps<TData extends DataRecord = DataRecord> {
+  columns: (DataTableColumn<TData> | SimpleColumn<TData>)[];
+  currentGroupBy: string | null;
+  onGroupByChange: (columnId: string | null) => void;
+  className?: string;
+}
+
+/**
+ * Dropdown component for selecting grouping column in DataTable.
+ * Allows users to group table rows by a specific column.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Grouping dropdown configuration
+ * @returns The rendered grouping dropdown
+ */
+export function GroupingDropdown<TData extends DataRecord>({ 
+  columns, 
+  currentGroupBy, 
+  onGroupByChange,
+  className
+}: GroupingDropdownProps<TData>) {
+  // Convert columns to a consistent format for grouping
+  const convertedColumns = columns.map(col => {
+    if ('accessorKey' in col && 'header' in col) {
+      // DataTableColumn format
+      return {
+        accessorKey: col.accessorKey,
+        header: typeof col.header === 'string' ? col.header : String(col.accessorKey),
+        enableGrouping: col.enableGrouping || false,
+      };
+    } else if ('key' in col && 'label' in col) {
+      // SimpleColumn format
+      return {
+        accessorKey: col.key,
+        header: col.label,
+        enableGrouping: false, // SimpleColumn doesn't support grouping by default
+      };
+    } else {
+      // Fallback for unknown format
+      return {
+        accessorKey: 'unknown',
+        header: 'Unknown',
+        enableGrouping: false,
+      };
+    }
+  });
+
+  const groupableColumns = convertedColumns.filter(col => col.enableGrouping && col.accessorKey);
+  
+  if (groupableColumns.length === 0) {
+    return null;
+  }
+
+  return (
+    <Select className="w-40">
+      <SelectTrigger asChild>
+        <Button 
+          variant="outline" 
+          className={className || ''}
+        >
+          <Group className="size-4 mr-2 flex-shrink-0" />
+          <span className="truncate">Grouping</span>
+        </Button>
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem
+          value="no-grouping"
+          onClick={() => onGroupByChange(null)}
+          className={`px-3 py-2 ${!currentGroupBy ? 'bg-main-50' : 'hover:bg-sec-50'}`}
+        >
+          No grouping
+        </SelectItem>
+        {groupableColumns.map((column) => {
+          const columnId = String(column.accessorKey);
+          const isSelected = currentGroupBy === columnId;
+          const displayName = column.header || String(column.accessorKey);
+          
+          return (
+            <SelectItem
+              key={columnId}
+              value={columnId}
+              onClick={() => onGroupByChange(columnId)}
+              className={`px-3 py-2 ${isSelected ? 'bg-main-50' : 'hover:bg-sec-50'}`}
+            >
+              {displayName}
+            </SelectItem>
+          );
+        })}
+      </SelectContent>
+    </Select>
+  );
+}

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

@@ -0,0 +1,548 @@
+/**
+ * @file Accessibility Utils Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils
+ * @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 with correct accessibility attributes', () => {
+      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(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);
+    });
+
+  });
+
+  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('handles multiple cleanup calls gracefully', () => {
+      initializeLiveRegion();
+      cleanupLiveRegion();
+      
+      // Second call should not throw
+      expect(() => cleanupLiveRegion()).not.toThrow();
+      expect(document.body.querySelector('.sr-only[aria-live]')).toBeNull();
+    });
+
+    it('handles cleanup when region does not exist', () => {
+      expect(() => cleanupLiveRegion()).not.toThrow();
+    });
+
+
+  });
+
+  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 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('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');
+    });
+  });
+});
+

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

@@ -231,7 +231,7 @@ export function getAriaSortValue(sortDirection: 'asc' | 'desc' | false): 'ascend
  * @param column - TanStack Table column instance
  * @returns ARIA sort value ('ascending', 'descending', 'none') or undefined if not sortable
  */
-export function getAriaSortState<TData>(column: { getCanSort?: () => boolean; getIsSorted?: () => 'asc' | 'desc' | false }): 'ascending' | 'descending' | 'none' | undefined {
+export function getAriaSortState<_TData>(column: { getCanSort?: () => boolean; getIsSorted?: () => 'asc' | 'desc' | false }): 'ascending' | 'descending' | 'none' | undefined {
   const isSortable = column.getCanSort ? column.getCanSort() : false;
   if (!isSortable) {
     return undefined;