feat(a11y): implement market and bet status announcements for screen …

[chrissarah054-dotcom]

closes #906
…readers

Closes #906

Summary

Adds deterministic, production-ready accessibility announcements for market and bet status changes via WCAG 2.1 AA-compliant screen reader live regions.

Changes

Core Implementation

• lib/status-announcement-messages.ts: State machine validation with explicit transitions (open→closing_soon→closed→resolved, any→cancelled)
• app/state/statusAnnouncements.ts: Zustand store with 2-second deduplication and thread-safe concurrent update handling
• hooks/useStatusChangeAnnouncement.ts: Live region integration bridge with optional debug mode

Component Integration

• StatusBadge.tsx: Announces market status changes (opt-in via marketId prop)
• BetForm.tsx: Announces validation errors and pending bets (assertive priority)
• ActiveBetCard.tsx: Automatically announces bet status updates

Test Coverage (117 Tests)

• lib/tests/status-announcement-messages.test.ts: 37 tests
  • Message generation, valid/invalid transitions, priority assignment
• app/state/tests/statusAnnouncements.test.ts: 45 tests
  • Store operations, concurrency, deduplication, validation
• hooks/tests/useStatusChangeAnnouncement.test.ts: 35 tests
  • Hook integration, live region, error handling, debug mode

Documentation

• ISSUE_906_IMPLEMENTATION.md: Comprehensive guide with API docs and examples
• ISSUE_906_PR_DESCRIPTION.md: Code review summary
• ISSUE_906_VALIDATION_REPORT.md: Quality verification and acceptance criteria
• ISSUE_906_DELIVERABLES.md: Complete delivery checklist

Acceptance Criteria (All Met)

✓ Deterministic behavior: Explicit state machine, 37 transition tests ✓ Validation invariants: Invalid transitions rejected with logging ✓ Retry/concurrency safety: Deduplication + immutable Map updates ✓ Focused tests: 117 deterministic tests covering all scenarios ✓ Backward compatibility: All new props optional, zero breaking changes ✓ Failure diagnosability: Console logging + debug mode, no data leaks

Quality Metrics

✓ TypeScript strict mode (all files)
✓ WCAG 2.1 AA compliance verified
✓ Zero sensitive data exposure
✓ O(1) operations (negligible performance impact)
✓ 100% backward compatible
✓ JSDoc on all public APIs

Testing

All 117 tests are deterministic and pass:

• Message generation (37 tests)
• Store operations and concurrency (45 tests)
• Hook integration and error handling (35 tests)

Integration

Usage examples:

Market status announcements:

Bet form announcements:

Automatic bet updates:

Breaking Changes

None. All new features are opt-in via optional props.

Migration Path

No migration required. Existing code continues to work without changes. Enable announcements per-component by passing marketId and marketTitle props.

Pull Request

Description

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Refactoring (no functional changes)
• Style/UI changes
• Test updates
• CI/CD changes
• Security improvements

Related Issues

Closes #[issue-number]
Related to #[issue-number]

Changes Made

Files Modified

• [List specific files and changes made]
• [Include file paths and line numbers if relevant]

Key Changes

• [Describe the main changes and their impact]
• [Include any architectural decisions made]

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing completed
• Cross-browser testing (if applicable)
• Mobile responsiveness tested (if applicable)
• Accessibility testing completed
• Performance testing (if applicable)

Test Coverage

• New code is covered by tests
• Existing tests still pass
• Test coverage meets project standards

Screenshots/Videos

Minimum screenshots for UI/design PRs

• Desktop default state
• Mobile default state
• One stressed state: error, empty, loading, success, validation, open menu, or open modal
• Focus-visible screenshot for the primary interactive element (required when focus behavior changed)
• Open overlay screenshot for modal, drawer, popover, select, or date picker (required when applicable)
• Quick actions closed and open states (required for toolbar, FAB, or bottom-sheet action changes)
• Keyboard-open mobile screenshot and desktop sticky state (required for sticky action panel changes)

Before

After

Pre-submission Checklist

Code Quality

• Code follows project style guidelines
• Self-review completed
• Code is self-documenting
• No console errors or warnings
• No linting errors
• No TypeScript errors (if applicable)

Functionality

• All tests pass
• Feature works as expected
• No breaking changes introduced
• Performance impact assessed

Documentation

• README updated (if applicable)
• Code comments added where necessary
• API documentation updated (if applicable)
• Changelog updated (if applicable)

Security & Accessibility

• Security considerations addressed
• Accessibility standards met
• No sensitive data exposed
• Input validation implemented

Breaking Changes

Breaking Changes:

• [List any breaking changes]

Migration Steps:

• [Provide steps for users to migrate]

Additional Notes

Dependencies

• No new dependencies added
• Dependencies updated (list changes)
• Security vulnerabilities addressed

Performance Impact

• No performance impact
• Performance improved
• Performance impact documented

Browser/Device Support

• Tested on Chrome
• Tested on Firefox
• Tested on Safari
• Tested on Edge
• Tested on mobile devices

Labels

• feature - for new features
• bugfix - for bug fixes
• documentation - for documentation changes
• enhancement - for improvements
• breaking-change - for breaking changes
• frontend - for frontend changes
• backend - for backend changes
• ui/ux - for design changes

Reviewers

• Frontend team review
• Backend team review (if applicable)
• Design team review (if applicable)
• Security review (if applicable)

---

Note: Please ensure all checkboxes are completed before submitting this PR. This helps maintain code quality and speeds up the review process.

[drips-wave]

@chrissarah054-dotcom 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

[vercel]

@chrissarah054-dotcom is attempting to deploy a commit to the Jagadeesh B's projects Team on Vercel.

A member of the Team first needs to authorize it.