@anymux/ui-kit 0.1.0

package/src/list/utils/ListAccessibility.ts

@@ -0,0 +1,367 @@
+// AICODE-NOTE: Accessibility utilities for list components
+export interface AccessibilityConfig {
+  role?: string;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
+  ariaMultiSelectable?: boolean;
+  ariaOrientation?: 'horizontal' | 'vertical';
+  tabIndex?: number;
+}
+
+export interface ItemAccessibilityConfig {
+  role?: string;
+  ariaLabel?: string;
+  ariaSelected?: boolean;
+  ariaExpanded?: boolean;
+  ariaLevel?: number;
+  ariaSetSize?: number;
+  ariaPosInSet?: number;
+  tabIndex?: number;
+}
+
+// AICODE-NOTE: Generate accessibility attributes for list container
+export function getListAccessibilityProps(config: {
+  viewType: string;
+  isMultiSelect: boolean;
+  totalItems: number;
+  selectedCount: number;
+  label?: string;
+  labelledBy?: string;
+  describedBy?: string;
+}): AccessibilityConfig {
+  const { viewType, isMultiSelect, totalItems, selectedCount, label, labelledBy, describedBy } = config;
+
+  // AICODE-NOTE: Base role depends on view type
+  let role = 'listbox';
+  let ariaOrientation: 'horizontal' | 'vertical' = 'vertical';
+
+  switch (viewType) {
+    case 'grid':
+    case 'masonry-horizontal':
+    case 'masonry-vertical':
+      role = 'grid';
+      ariaOrientation = viewType === 'masonry-horizontal' ? 'horizontal' : 'vertical';
+      break;
+    case 'details':
+      role = 'table';
+      break;
+    default:
+      role = 'listbox';
+  }
+
+  return {
+    role,
+    ariaLabel: label || `${viewType} view with ${totalItems} items, ${selectedCount} selected`,
+    ariaLabelledBy: labelledBy,
+    ariaDescribedBy: describedBy,
+    ariaMultiSelectable: isMultiSelect,
+    ariaOrientation,
+    tabIndex: 0
+  };
+}
+
+// AICODE-NOTE: Generate accessibility attributes for list items
+export function getItemAccessibilityProps(config: {
+  item: any;
+  index: number;
+  totalItems: number;
+  isSelected: boolean;
+  isFocused: boolean;
+  viewType: string;
+  isExpandable?: boolean;
+  isExpanded?: boolean;
+  level?: number;
+}): ItemAccessibilityConfig {
+  const { 
+    item, 
+    index, 
+    totalItems, 
+    isSelected, 
+    isFocused, 
+    viewType, 
+    isExpandable = false, 
+    isExpanded, 
+    level = 1 
+  } = config;
+
+  // AICODE-NOTE: Base role depends on view type
+  let role = 'option';
+  
+  switch (viewType) {
+    case 'grid':
+    case 'masonry-horizontal':
+    case 'masonry-vertical':
+      role = 'gridcell';
+      break;
+    case 'details':
+      role = 'row';
+      break;
+    default:
+      role = 'option';
+  }
+
+  // AICODE-NOTE: Generate descriptive label
+  const itemType = item?.type || 'item';
+  const itemSize = item?.size ? `, ${formatFileSize(item.size)}` : '';
+  const itemDate = item?.modifiedDate ? `, modified ${formatDate(item.modifiedDate)}` : '';
+  const selectionState = isSelected ? ', selected' : '';
+  const expandState = isExpandable ? (isExpanded ? ', expanded' : ', collapsed') : '';
+  
+  const ariaLabel = `${item?.name || 'Unknown item'}, ${itemType}${itemSize}${itemDate}${selectionState}${expandState}`;
+
+  return {
+    role,
+    ariaLabel,
+    ariaSelected: isSelected,
+    ariaExpanded: isExpandable ? isExpanded : undefined,
+    ariaLevel: level,
+    ariaSetSize: totalItems,
+    ariaPosInSet: index + 1,
+    tabIndex: isFocused ? 0 : -1
+  };
+}
+
+// AICODE-NOTE: Generate live region announcements for screen readers
+export function createLiveRegionAnnouncement(config: {
+  action: 'select' | 'deselect' | 'focus' | 'activate' | 'load' | 'error';
+  itemName?: string;
+  itemCount?: number;
+  selectedCount?: number;
+  totalCount?: number;
+  errorMessage?: string;
+}): string {
+  const { action, itemName, itemCount, selectedCount, totalCount, errorMessage } = config;
+
+  switch (action) {
+    case 'select':
+      if (itemName && selectedCount !== undefined) {
+        return `${itemName} selected. ${selectedCount} of ${totalCount} items selected.`;
+      }
+      return 'Item selected';
+
+    case 'deselect':
+      if (itemName && selectedCount !== undefined) {
+        return `${itemName} deselected. ${selectedCount} of ${totalCount} items selected.`;
+      }
+      return 'Item deselected';
+
+    case 'focus':
+      return itemName ? `${itemName} focused` : 'Item focused';
+
+    case 'activate':
+      return itemName ? `${itemName} activated` : 'Item activated';
+
+    case 'load':
+      if (itemCount !== undefined) {
+        return `${itemCount} items loaded`;
+      }
+      return 'Items loaded';
+
+    case 'error':
+      return errorMessage || 'An error occurred';
+
+    default:
+      return '';
+  }
+}
+
+// AICODE-NOTE: Keyboard navigation helpers
+export interface KeyboardNavigationConfig {
+  currentIndex: number;
+  totalItems: number;
+  itemsPerRow?: number;
+  viewType: string;
+}
+
+export function getNextFocusIndex(
+  key: string,
+  config: KeyboardNavigationConfig
+): number | null {
+  const { currentIndex, totalItems, itemsPerRow = 1, viewType } = config;
+
+  switch (key) {
+    case 'ArrowDown':
+      if (viewType === 'grid' || viewType.includes('masonry')) {
+        // AICODE-NOTE: Grid navigation - move down by itemsPerRow
+        const nextIndex = currentIndex + itemsPerRow;
+        return nextIndex < totalItems ? nextIndex : null;
+      } else {
+        // AICODE-NOTE: List navigation - next item
+        return currentIndex < totalItems - 1 ? currentIndex + 1 : null;
+      }
+
+    case 'ArrowUp':
+      if (viewType === 'grid' || viewType.includes('masonry')) {
+        // AICODE-NOTE: Grid navigation - move up by itemsPerRow
+        const prevIndex = currentIndex - itemsPerRow;
+        return prevIndex >= 0 ? prevIndex : null;
+      } else {
+        // AICODE-NOTE: List navigation - previous item
+        return currentIndex > 0 ? currentIndex - 1 : null;
+      }
+
+    case 'ArrowRight':
+      if (viewType === 'grid' || viewType.includes('masonry')) {
+        // AICODE-NOTE: Grid navigation - next item in row
+        const nextIndex = currentIndex + 1;
+        const currentRow = Math.floor(currentIndex / itemsPerRow);
+        const nextRow = Math.floor(nextIndex / itemsPerRow);
+        return nextIndex < totalItems && currentRow === nextRow ? nextIndex : null;
+      }
+      return null;
+
+    case 'ArrowLeft':
+      if (viewType === 'grid' || viewType.includes('masonry')) {
+        // AICODE-NOTE: Grid navigation - previous item in row
+        const prevIndex = currentIndex - 1;
+        const currentRow = Math.floor(currentIndex / itemsPerRow);
+        const prevRow = Math.floor(prevIndex / itemsPerRow);
+        return prevIndex >= 0 && currentRow === prevRow ? prevIndex : null;
+      }
+      return null;
+
+    case 'Home':
+      return 0;
+
+    case 'End':
+      return totalItems - 1;
+
+    case 'PageUp':
+      // AICODE-NOTE: Move up by approximately 10 items or one screen
+      const pageUpIndex = Math.max(0, currentIndex - 10);
+      return pageUpIndex !== currentIndex ? pageUpIndex : null;
+
+    case 'PageDown':
+      // AICODE-NOTE: Move down by approximately 10 items or one screen
+      const pageDownIndex = Math.min(totalItems - 1, currentIndex + 10);
+      return pageDownIndex !== currentIndex ? pageDownIndex : null;
+
+    default:
+      return null;
+  }
+}
+
+// AICODE-NOTE: Format file size for screen readers
+function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 bytes';
+  
+  const k = 1024;
+  const sizes = ['bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+
+// AICODE-NOTE: Format date for screen readers
+function formatDate(date: Date | string): string {
+  const dateObj = typeof date === 'string' ? new Date(date) : date;
+  return dateObj.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit'
+  });
+}
+
+// AICODE-NOTE: Focus management utilities
+export class FocusManager {
+  private focusedElement: HTMLElement | null = null;
+  private focusHistory: HTMLElement[] = [];
+
+  // AICODE-NOTE: Save current focus for restoration
+  saveFocus(): void {
+    const activeElement = document.activeElement as HTMLElement;
+    if (activeElement && activeElement !== document.body) {
+      this.focusedElement = activeElement;
+      this.focusHistory.push(activeElement);
+    }
+  }
+
+  // AICODE-NOTE: Restore previously saved focus
+  restoreFocus(): boolean {
+    if (this.focusedElement && document.contains(this.focusedElement)) {
+      this.focusedElement.focus();
+      return true;
+    }
+    
+    // AICODE-NOTE: Try focus history
+    while (this.focusHistory.length > 0) {
+      const element = this.focusHistory.pop();
+      if (element && document.contains(element)) {
+        element.focus();
+        return true;
+      }
+    }
+    
+    return false;
+  }
+
+  // AICODE-NOTE: Focus first focusable element in container
+  focusFirst(container: HTMLElement): boolean {
+    const focusable = this.getFocusableElements(container);
+    if (focusable.length > 0 && focusable[0]) {
+      focusable[0].focus();
+      return true;
+    }
+    return false;
+  }
+
+  // AICODE-NOTE: Focus last focusable element in container
+  focusLast(container: HTMLElement): boolean {
+    const focusable = this.getFocusableElements(container);
+    const lastElement = focusable[focusable.length - 1];
+    if (focusable.length > 0 && lastElement) {
+      lastElement.focus();
+      return true;
+    }
+    return false;
+  }
+
+  // AICODE-NOTE: Get all focusable elements in container
+  private getFocusableElements(container: HTMLElement): HTMLElement[] {
+    const focusableSelectors = [
+      'button:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      'a[href]',
+      '[tabindex]:not([tabindex="-1"])'
+    ].join(', ');
+
+    return Array.from(container.querySelectorAll(focusableSelectors)) as HTMLElement[];
+  }
+}
+
+// AICODE-NOTE: Create live region element for announcements
+export function createLiveRegion(id: string = 'list-live-region'): HTMLElement {
+  let liveRegion = document.getElementById(id);
+  
+  if (!liveRegion) {
+    liveRegion = document.createElement('div');
+    liveRegion.id = id;
+    liveRegion.setAttribute('aria-live', 'polite');
+    liveRegion.setAttribute('aria-atomic', 'true');
+    liveRegion.style.position = 'absolute';
+    liveRegion.style.left = '-10000px';
+    liveRegion.style.width = '1px';
+    liveRegion.style.height = '1px';
+    liveRegion.style.overflow = 'hidden';
+    document.body.appendChild(liveRegion);
+  }
+  
+  return liveRegion;
+}
+
+// AICODE-NOTE: Announce message to screen readers
+export function announceToScreenReader(message: string, priority: 'polite' | 'assertive' = 'polite'): void {
+  const liveRegion = createLiveRegion();
+  liveRegion.setAttribute('aria-live', priority);
+  
+  // AICODE-NOTE: Clear and set new message
+  liveRegion.textContent = '';
+  setTimeout(() => {
+    liveRegion.textContent = message;
+  }, 100);
+}