A11y/toast 21 focus

[shogun444]

Closes #729

Adds comprehensive focus management for toast notifications to improve keyboard and screen-reader accessibility during toast and route transitions.

Summary

• Moves focus to the most relevant interactive control when a toast appears
  • Action button (when present)
  • Otherwise the dismiss button
• Restores focus to the element that triggered the toast after the last visible toast is dismissed
• Preserves user intent by avoiding focus restoration if focus has already been moved elsewhere
• Falls back to the application's <main> element when the original trigger is no longer available
• Traps keyboard navigation within the toast viewport while toast interactions are active
• Preserves existing toast behavior with no visual or styling changes

---

Type of Change

• Bug fix (non-breaking change that resolves an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Refactor (no functional change, internal code improvement)
• Documentation update

---

Pre-flight Checklist

• npm run lint passes with no errors
• npm test passes with no failures
• npm run build completes successfully

---

Testing & Coverage

• Module test coverage for impacted files meets or exceeds the 95% minimum threshold
• If this PR adds or modifies UI components, accessibility tests were written using the shared utilities in src/test-utils/a11y.tsx

What was tested?

Added focus-management tests covering:

• Focus moves to the dismiss button when a toast opens
• Focus moves to the action button when an action is available
• Focus follows the newest toast when multiple toasts are displayed
• Focus is restored after manual dismissal
• Focus is restored after auto-dismiss
• Focus is restored after toast eviction
• Fallback focus to <main> when the trigger element has been removed
• Quiet mode does not change focus
• Tab and Shift+Tab remain within the toast viewport
• Newest toast receives focus after eviction
• Focus is not restored if the user intentionally moved it elsewhere before the toast closed

Project verification:

• npm test — 1289 tests passed (74 test suites)
• npm run lint — passed
• npm run build — passed with no TypeScript errors

---

Accessibility & Security Notes

Accessibility

• Added deterministic focus management for toast lifecycle events
• Restores focus to the triggering element after the final toast closes
• Prevents unexpected focus jumps when users intentionally move focus elsewhere
• Provides keyboard-only navigation within the toast viewport
• Preserves existing ARIA roles and visual behavior

Security

N/A — this change only affects client-side focus management and does not modify authentication, authorization, wallet logic, API behavior, or user data handling.

[drips-wave]

@shogun444 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits