<!-- aria-atomic="true" → announce the WHOLE region text on any mutation -->
<div aria-live="polite" aria-atomic="true">
  <!-- If "3 results" changes to "4 results", announces: "4 results for workspace" -->
  <!-- Without aria-atomic, some AT would only announce "4" — the changed fragment -->
  4 results for workspace
</div>

<!-- aria-relevant controls which mutation types trigger announcements -->
<div
  aria-live="polite"
  aria-relevant="additions text"
  aria-atomic="false"
>
  <!-- Only newly added text nodes are announced; removals are silent -->
</div>

// ❌ Anti-pattern: each widget manages its own live region
// When three components update simultaneously, AT announces three messages in rapid succession
function SearchBar() {
  return (
    <>
      <input ... />
      <div aria-live="polite">{resultCount} results</div>  {/* ← Live region #1 */}
    </>
  );
}

function ActivityFeed() {
  return (
    <>
      <div aria-live="polite">{newItemCount} new items</div>  {/* ← Live region #2 */}
      <FeedList ... />
    </>
  );
}

function NotificationBell() {
  return (
    <>
      <div aria-live="assertive">{errorMessage}</div>  {/* ← Live region #3 */}
      <button>...</button>
    </>
  );
}

// Announcement priority types
type AnnouncePriority = 'polite' | 'assertive';

interface AnnounceFunction {
  (message: string, priority?: AnnouncePriority): void;
}

interface AnnouncerContextValue {
  announce: AnnounceFunction;
}

const AnnouncerContext = createContext<AnnouncerContextValue | null>(null);

export function LiveAnnouncerProvider({ children }: { children: ReactNode }) {
  const politeRef = useRef<HTMLDivElement>(null);
  const assertiveRef = useRef<HTMLDivElement>(null);

  const announce = useCallback((message: string, priority: AnnouncePriority = 'polite') => {
    const target = priority === 'assertive' ? assertiveRef.current : politeRef.current;
    if (!target) return;

    // Clear → set pattern: some AT require a brief empty state to re-announce
    // the same message string on consecutive calls (e.g., "Saved." → "Saved.")
    target.textContent = '';
    // rAF ensures the clear is flushed to the DOM before the message is injected
    requestAnimationFrame(() => {
      target.textContent = message;
    });
  }, []);

  return (
    <AnnouncerContext.Provider value={{ announce }}>
      {children}
      {/* These elements are mounted once at the root — never in component trees */}
      <div
        ref={politeRef}
        aria-live="polite"
        aria-atomic="true"
        className="sr-only"
      />
      <div
        ref={assertiveRef}
        aria-live="assertive"
        aria-atomic="true"
        className="sr-only"
      />
    </AnnouncerContext.Provider>
  );
}

export function useAnnouncer(): AnnounceFunction {
  const ctx = useContext(AnnouncerContext);
  if (!ctx) throw new Error('useAnnouncer must be used within LiveAnnouncerProvider');
  return ctx.announce;
}

function useQueuedAnnouncer(targetRef: RefObject<HTMLDivElement | null>) {
  const queue = useRef<string[]>([]);
  const isAnnouncing = useRef(false);

  const processQueue = useCallback(() => {
    if (isAnnouncing.current || queue.current.length === 0) return;
    isAnnouncing.current = true;

    const message = queue.current.shift()!;
    const target = targetRef.current;
    if (!target) { isAnnouncing.current = false; return; }

    target.textContent = '';
    requestAnimationFrame(() => {
      target.textContent = message;
      // Wait for speech to complete before processing next message
      // 750ms is a conservative estimate; production systems use speech synthesis events
      setTimeout(() => {
        isAnnouncing.current = false;
        processQueue();
      }, 750);
    });
  }, [targetRef]);

  const enqueue = useCallback((message: string) => {
    queue.current.push(message);
    processQueue();
  }, [processQueue]);

  return enqueue;
}

interface ActivityEvent {
  id: string;
  channelName: string;
  type: 'message' | 'join' | 'leave' | 'reaction';
}

function useActivityFeedAnnouncer(events: ActivityEvent[]) {
  const announce = useAnnouncer();
  const batchRef = useRef<ActivityEvent[]>([]);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const prevLengthRef = useRef(events.length);

  useEffect(() => {
    const newEvents = events.slice(prevLengthRef.current);
    prevLengthRef.current = events.length;

    if (newEvents.length === 0) return;

    // Accumulate new events in the batch buffer
    batchRef.current.push(...newEvents);

    // Debounce: announce after 2 seconds of no new events
    if (timerRef.current) clearTimeout(timerRef.current);
    timerRef.current = setTimeout(() => {
      const batch = batchRef.current;
      if (batch.length === 0) return;

      // Compose a human-readable batch summary
      const channelCounts = batch.reduce<Record<string, number>>((acc, ev) => {
        acc[ev.channelName] = (acc[ev.channelName] ?? 0) + 1;
        return acc;
      }, {});

      const summary = Object.entries(channelCounts)
        .map(([channel, count]) => `${count} new ${count === 1 ? 'message' : 'messages'} in ${channel}`)
        .join(', ');

      announce(summary, 'polite');
      batchRef.current = [];
    }, 2000);

    return () => {
      if (timerRef.current) clearTimeout(timerRef.current);
    };
  }, [events, announce]);
}

type FormStatus = 'idle' | 'submitting' | 'success' | 'error';

function useFormStatusAnnouncer(status: FormStatus, errorMessage?: string) {
  const announce = useAnnouncer();

  useEffect(() => {
    switch (status) {
      case 'submitting':
        announce('Saving changes, please wait.', 'polite');
        break;
      case 'success':
        announce('Changes saved successfully.', 'polite');
        break;
      case 'error':
        announce(
          errorMessage
            ? `Failed to save: ${errorMessage}`
            : 'An error occurred. Please try again.',
          'assertive'  // Error on save is assertive — user must know
        );
        break;
      default:
        break;
    }
  }, [status, errorMessage, announce]);
}

// Usage in the Portal Canvas settings form
function UserProfileForm() {
  const [status, setStatus] = useState<FormStatus>('idle');
  const [errorMessage, setErrorMessage] = useState<string | undefined>();

  useFormStatusAnnouncer(status, errorMessage);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setStatus('submitting');
    try {
      await saveProfileSettings();
      setStatus('success');
    } catch (err) {
      setStatus('error');
      setErrorMessage(err instanceof Error ? err.message : 'Unknown error');
    }
  }

  return (
    <form onSubmit={handleSubmit} aria-labelledby="settings-heading">
      {/* Fields from Part 1 */}
      <button type="submit" disabled={status === 'submitting'}>
        {status === 'submitting' ? 'Saving…' : 'Save changes'}
      </button>
      {/* Visual status display — screen reader users get the live announcement */}
      {status === 'success' && <p aria-hidden="true">Changes saved ✓</p>}
    </form>
  );
}