Rithika taking over for Aditya-feat: Add Smart Insights and Predictive Utilization Analysis to the Utilization Chart

[Aditya-gam]

Description

This PR upgrades the BM Utilization Chart from a historical-only view into a planning and decision-support UI. It adds forecast modes, backend-driven smart insights, maintenance/resource recommendations, and report export, while also hardening accessibility and async request behavior.

Related PRS (if any):

• Frontend baseline: #3882
• Backend PR: #2115

Main changes explained:

Created/Updated Files:

• src/components/BMDashboard/UtilizationChart/UtilizationChart.jsx

  • Refactored the page into an orchestrator that coordinates:
    • filters (tool, project, startDate, endDate)
    • forecast mode switching (historical, forecast30, forecastFull)
    • chart data + insights data loading states
    • export action wiring
  • Integrates backend endpoints through hooks:
    • GET /api/tools/utilization with mode
    • GET /api/tools/utilization/insights
  • Enhances chart behavior:
    • traffic-light colored bars from classification.trafficLight
    • forecast dataset overlay for non-historical modes
    • warning banner for backend fallback warnings
    • custom Chart.js plugin draws status dots by Y-axis labels
  • Accessibility improvements:
    • radiogroup toggle integration
    • aria-live chart status announcements
    • chart wrapper with descriptive role="img"

• src/components/BMDashboard/UtilizationChart/UtilizationChart.module.css

  • Expanded to a full-featured stylesheet covering:
    • forecast toggle UI
    • summary cards
    • recommendation/alert/balancing panels
    • export controls
    • loading/empty/error/warning states
    • Keeps CSS-module + CSS-variable approach for light/dark mode.
    • Adds responsive layouts for 1024/768/576 breakpoints.

• src/components/BMDashboard/UtilizationChart/hooks/useUtilizationData.js

  • New data hook for utilization payload retrieval.
  • Sends params: tool, project, startDate, endDate, mode.
  • Adds cancellation with AbortController to prevent race conditions when users rapidly change filters/mode.
  • Handles backend validation errors (400) vs generic failures.

• src/components/BMDashboard/UtilizationChart/hooks/useUtilizationInsights.js

  • New data hook for insights payload retrieval.
  • Sends params: tool, project, startDate, endDate.
  • Adds in-flight request cancellation and guarded loading transitions.
  • Maintains normalized initial structure: recommendations, maintenanceAlerts, resourceBalancing, summary.

• src/components/BMDashboard/UtilizationChart/constants.js

  • New feature constants:
    • forecast mode enums/labels
    • traffic-light color/label maps
    • classification labels
    • urgency/confidence style maps
    • export format constants (pdf, csv)

• src/components/BMDashboard/UtilizationChart/ForecastModeToggle.jsx

  • New segmented control for forecast mode selection.
  • Supports keyboard navigation (ArrowLeft/Right/Up/Down) with roving focus for accessible radio group behavior.

• src/components/BMDashboard/UtilizationChart/InsightsSummaryBar.jsx

  • New summary strip rendering totalToolTypes, averageUtilization, normal, underUtilized, and overUtilized from insights summary.

• src/components/BMDashboard/UtilizationChart/RecommendationPanel.jsx

  • New recommendations panel showing per-tool recommendation cards with classification badge, action text, and utilization percentage.

• src/components/BMDashboard/UtilizationChart/MaintenanceAlertPanel.jsx

  • New alerts panel for backend maintenanceAlerts.
  • Sorts alerts to prioritize high urgency before medium.

• src/components/BMDashboard/UtilizationChart/ResourceBalancingPanel.jsx (+35 / -0)

  • New panel for backend resource balancing suggestions.
  • Renders transfer-style guidance (fromTool to optional toTool) and rationale text.

• src/components/BMDashboard/UtilizationChart/ExportReportButton.jsx

  • New export controls for report download via GET /api/tools/utilization/export.
  • Supports both format=pdf and format=csv with responseType: 'blob'.
  • Parses Content-Disposition filename fallback and triggers browser download.
  • Uses format-specific loading feedback (Exporting... on active format).

• src/utils/URL.js

  • Added endpoint constants:
    • BM_TOOL_UTILIZATION
    • BM_TOOL_UTILIZATION_INSIGHTS
    • BM_TOOL_UTILIZATION_EXPORT

Key Implementation Details:

• Forecast Modes
  • UI modes map directly to backend expectations:
    • historical
    • forecast30
    • forecastFull
• API Parameter Mapping
  • Utilization request params:
    • tool, project, startDate, endDate, mode
  • Insights request params:
    • tool, project, startDate, endDate
  • Export request params:
    • format, tool, project, startDate, endDate
• Chart Rendering Strategy
  • Horizontal bar chart retained (Chart.js + react-chartjs-2).
  • Historical utilization is the primary dataset.
  • Forecast appears as a second dataset in non-historical modes.
  • Y-axis traffic-light markers are drawn via a custom plugin.
• Concurrency/Race-condition Handling
  • Both hooks abort previous in-flight requests before launching a new one.
  • Prevents stale responses from overriding fresher user selections.
• Accessibility Enhancements
  • Forecast toggle supports keyboard arrows and focus movement.
  • Live chart state announcements for loading/error/empty/updated states.
  • Semantic labeling added around chart output for screen readers.

How to test:

1. Check into current branch: Aditya-feat/Add-Smart-Insights-and-Predictive-Utilization-Analysis-to-the-Utilization-Chart
2. Reinstall dependencies and clear cache: rm -rf node_modules && yarn cache clean
3. Run yarn install and start the app: yarn start:local
4. Login using Admin/Owner Login.
5. Test Utilization Chart feature:
   • Navigate to /UtilizationChart
   • Select filters (Tool, Project, Start Date, End Date), then click Apply
   • Toggle forecast modes and verify request/visual behavior:
     • Historical: only utilization bars
     • 30-Day Forecast: forecast dataset appears
     • Full Project Schedule: forecast dataset appears; warning banner appears if backend returns warning
   • Verify insights sections render with backend content:
     • Recommendations
     • Maintenance Alerts
     • Resource Balancing
     • Summary metrics strip
   • Trigger export:
     • Click PDF and verify download + button loading text
     • Click CSV and verify download + button loading text
6. Verify:
   • Expected chart coloring by classification.trafficLight
   • Tooltip and datalabels reflect utilization/downtime/classification
   • Keyboard accessibility on forecast toggle (arrow keys)
   • Rapid mode/filter changes do not produce stale data flicker
   • Error handling for failed API responses shows user-facing fallback states

Screenshots or videos of changes:

• Light Mode:

• Dark Mode:

• Test Video:

TestVideo.mov

Note:

• Performance Considerations:
  • Added request cancellation in hooks to reduce stale render churn during rapid user interaction.
  • Chart and options use memoization to reduce unnecessary recalculations.
• Backward Compatibility:
  • Existing Utilization Chart route and core workflow remain intact.
  • Enhancements are additive to the existing page structure.

[netlify]

✅ Deploy Preview for highestgoodnetwork-dev ready!

Name	Link
🔨 Latest commit	58d8143
🔍 Latest deploy log	https://app.netlify.com/projects/highestgoodnetwork-dev/deploys/6a3b58813530620008f9f513
😎 Deploy Preview	https://deploy-preview-5073--highestgoodnetwork-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sonarqubecloud]

Quality Gate passed

Issues
26 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rajanidi1999]

Hi Aditya,
The Tool Utilization Analysis page is loading correctly and displays the data in a clear and structured format. The filters for tool selection, building, and date range are visible and easy to use, and the Apply button is accessible.

[Anusha-Gali]

Hi Aditya,

I have reviewed your PR locally and it works as per requirement , filters, toggle, prediction and the exports.

[HemanthNidamanuru]

Hi,

I reviewed and tested this PR locally. The UI is entirely different from the expected design, and the insights section is not matching properly. Also, PDF and CSV export functionalities are not working.

[DeepighaJ]

Hi

• Checked out to current branch and tested PR locally.
• The chart appears to have overlapped values with 0% values shown along with other values making everything collapsed.
• There is this yellow dots marked along Y axis not sure its intended to be there.
• In light mode the calendar month navigator is not visible.
• The pdf and csv are working as expected.
• Excessive empty whitespace is displayed below the report content, resulting in inefficient use of screen space and requiring unnecessary scrolling.

[rithika-paii]

Hi @DeepighaJ,
Thank you for the detailed review. Here's an update on each point:

• Overlapping values / 0% collapsed bars — Fixed. The chart now renders correctly with no overlapping labels or collapsed bars.
• Yellow dots on Y axis — These are intentional. They are part of the traffic-light indicator plugin that color-codes each tool's utilization level (green/yellow/red). They are a core part of the Smart Insights feature design.
• Calendar month navigator not visible in light mode — Fixed. The calendar now displays correctly in both light and dark mode.
• PDF and CSV — Confirmed working as expected.
• Excessive whitespace below report content — Fixed. The layout has been tightened up.

All CI checks are passing and SonarQube is at 0 issues. Please let me know if you'd like me to make any further changes!

[DeepighaJ]

Application fails to start because src/routes.jsx contains unresolved Git merge conflict markers (<<<<<<< HEAD, =======, >>>>>>>). The project cannot compile until the conflict is resolved.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud