Accessibility Announcements

import { announce, AnnouncerPriority, DATA_MDC_DOM_ANNOUNCE } from '@material/dom/announce';

/**
 * Announces the given message with optional priority, defaulting to "polite"
 * @param message - The message to announce to screen readers
 * @param options - Configuration options for the announcement
 */
function announce(message: string, options?: AnnouncerMessageOptions): void;

interface AnnouncerMessageOptions {
  /**
   * The priority level for the announcement
   * @default AnnouncerPriority.POLITE
   */
  priority?: AnnouncerPriority;
  
  /**
   * The document context for the announcement
   * @default document
   */
  ownerDocument?: Document;
}

enum AnnouncerPriority {
  /**
   * Polite announcements wait for the user to finish their current activity
   * This is the default and recommended for most use cases
   */
  POLITE = 'polite',
  
  /**
   * Assertive announcements interrupt the user's current activity
   * Use sparingly for urgent messages like errors
   */
  ASSERTIVE = 'assertive'
}

/**
 * Data attribute added to live region elements for identification
 */
const DATA_MDC_DOM_ANNOUNCE: 'data-mdc-dom-announce';

import { announce } from '@material/dom/announce';

// Simple polite announcement (default)
announce('Form saved successfully');

// Equivalent explicit polite announcement
announce('Form saved successfully', { 
  priority: AnnouncerPriority.POLITE 
});

import { announce, AnnouncerPriority } from '@material/dom/announce';

// Assertive announcement for errors
announce('Error: Please correct the highlighted fields', {
  priority: AnnouncerPriority.ASSERTIVE
});

// Network error announcement
announce('Connection lost. Attempting to reconnect...', {
  priority: AnnouncerPriority.ASSERTIVE
});

import { announce } from '@material/dom/announce';

// Announce in iframe context
const iframe = document.querySelector('iframe');
const iframeDoc = iframe.contentDocument;

announce('Content loaded in iframe', {
  ownerDocument: iframeDoc
});

// Announce in modal dialog context
const modal = document.querySelector('.modal');
const modalDoc = modal.ownerDocument;

announce('Modal opened', {
  ownerDocument: modalDoc
});

import { announce, AnnouncerPriority } from '@material/dom/announce';

function validateForm(form: HTMLFormElement) {
  const errors = findValidationErrors(form);
  
  if (errors.length > 0) {
    const errorMessage = `${errors.length} validation error${errors.length > 1 ? 's' : ''} found`;
    announce(errorMessage, {
      priority: AnnouncerPriority.ASSERTIVE
    });
  } else {
    announce('Form is valid and ready to submit');
  }
}

import { announce } from '@material/dom/announce';

class SearchResults {
  updateResults(results: any[]) {
    this.renderResults(results);
    
    // Announce results to screen readers
    const count = results.length;
    if (count === 0) {
      announce('No results found');
    } else {
      announce(`${count} result${count > 1 ? 's' : ''} found`);
    }
  }
  
  showLoadingState() {
    announce('Searching...');
  }
  
  showError(error: string) {
    announce(`Search error: ${error}`, {
      priority: AnnouncerPriority.ASSERTIVE
    });
  }
}

import { announce } from '@material/dom/announce';

class FileUpload {
  updateProgress(percent: number) {
    // Update visual progress bar
    this.progressBar.style.width = `${percent}%`;
    
    // Announce progress at intervals
    if (percent % 25 === 0) {
      announce(`Upload ${percent}% complete`);
    }
  }
  
  onComplete() {
    announce('File upload completed successfully');
  }
  
  onError(error: string) {
    announce(`Upload failed: ${error}`, {
      priority: AnnouncerPriority.ASSERTIVE
    });
  }
}

// Good
announce('3 items added to cart');

// Too verbose  
announce('The user has successfully added three items to their shopping cart and can now proceed to checkout');

// Good
announce('Page 2 of 5 loaded');

// Missing context
announce('Page loaded');

// Consistent
announce('Form saved');
announce('Form deleted');

// Inconsistent
announce('Form has been saved successfully');
announce('Deletion complete');