feat: implement interactive guided breathing tool (Issue #1805)

[Kadaliswarna]

PR Description

This PR implements the Interactive Guided Breathing Tool for Stress & Panic Relief as requested in Issue #1805.

Changes in detail:

• Created a new BreathingTool.tsx component that supports both "4-7-8" and "Box" breathing exercises.
• Added smooth CSS scale animations for the breathing circle synced with the inhale, hold, and exhale phases.
• Integrated the component natively into the WellnessDashboardScreen.tsx.
• Ensured state resets gracefully during Start, Pause, Resume, and Stop actions.
• Integrated the existing wellness logging endpoint (LOG_WELLNESS_METRICS in APIUtils.ts) to securely submit the completed breathingSessionMinutes payload to the backend when a session ends.

Type of Change

• Bug fix (change which fixes an issue)
• New feature (change which adds functionality)
• Documentation update

Select your work-area

• Frontend
• Backend
• Documentation
• Others

Related Issue

#1805

Add your Work Example

📷 (Add screenshot here)

Fixes (mention the issue number which this fixes)

#closes #1805

Checklist

• I have updated my branch and synced it with the project's 'develop' branch before making this PR.
• I have optimized the file changes.
• I have added a snapshot of my work example.
• I have made a PR to the project's develop branch.

Undertaking

• My code follows the style guidelines of this project.

• I have performed a self-review of my code.

• I have commented my code, particularly in hard-to-understand areas.

• I have made corresponding changes to the documentation.

• I have checked for plagiarism and assure its authenticity.

• I have read and followed the code of conduct for this repository. I understand that violation of this undertaking may have legal consequences.

• I Agree

[github-actions]

Thank you @, for creating the PR and contributing to our UltimateHealth project 💗.
Our team will review the PR and will reach out to you soon! 😇
Make sure that you have marked all the tasks that you are done with ✅.
Thank you for your patience! 😀

[github-actions]

Automated Review Feedback

Provide actionable comments grouped by severity:

Important

• Missing Tests: The BreathingTool component involves complex state management, timing logic, and animations. While the current implementation appears correct, the absence of unit or integration tests makes it difficult to ensure correctness across all scenarios and guard against future regressions. Consider adding tests for:
  • Phase transitions and cycle completion logic.
  • Start, pause, resume, and stop functionalities.
  • Data logging behavior for different session durations.

Suggestions

• Logging Short Sessions: The submitSessionData function only logs sessions if breathingSessionMinutes is greater than 0. This means sessions shorter than 60 seconds will not be logged. Please clarify if this is the intended behavior. If not, consider:
  • Rounding up to 1 minute for any session greater than 0 seconds.
  • Modifying the backend endpoint to accept breathingSessionSeconds for more granular logging.
• Timer useEffect Comments: The useEffect hook responsible for the timer logic is quite dense, handling phase transitions, cycle completion, and animation updates. Adding a few more comments within this hook could significantly improve its readability and maintainability for future contributors.
• DEFAULT_CYCLES Configurability: The DEFAULT_CYCLES constant is currently hardcoded within the component. For increased flexibility, consider making this a configurable prop that can be passed to the BreathingTool component, allowing different parts of the application to specify the desired number of cycles.
• User-Facing Error Handling for API: While console.error is used for API call failures in submitSessionData, consider adding a user-facing alert or toast notification if the wellness metrics fail to log. This would provide better feedback to the user, especially if they expect their completed session to be recorded.

Maintainer Note:

Once the initial automated feedback has been addressed, maintainer @SB2318 will review the pull request for final evaluation.

[Kadaliswarna]

Hi @SB2318,

I've addressed the automated review feedback in the latest commit by improving the implementation and refactoring the component where appropriate.

Updates made
Added tests for the breathing tool flow and session behavior.
Made the default breathing cycles configurable.
Improved inline comments for the timer and phase transition logic.
Enhanced user-facing error handling for wellness metrics logging.
Refined the implementation while keeping the existing Wellness Metrics API unchanged and avoiding any backend/model modifications.

The PR is now up to date, passes the available checks, and is ready for review.

Kindly review the PR when you have time. Thank you!