[Sprint 6b]: Heatmap Enhancements 🥵 - Elki & Hansini & Chiara

[danglorioso]

💻 Summary

In this sprint, you will add a variety of miscellaneous features to our existing heat map in order to make it as intuitive and useful as possible. This includes refining the school tooltip popups, adding export functionality, modifying the region borders, adding share functionality, and other minor features outlined below.

Goals of this sprint:

• Enhance the map interactivity by adding a variety of features that link to dynamically generated school profile pages and incorporate export and sharing functionality.
• Refine the visual presentation of our heat map to make it look beautiful. At the same time, add features that improve the user experience.
• Gain experience working with a heatmap component, exporting figures to PDF, and generating parameterized states.

⚙️ Setup

Before starting:

1. PLEASE: **Pull the latest changes from main: git pull
2. Create a new branch for this sprint.
3. Install dependencies.
4. Run the dev server and verify the site builds.
5. Confirm everything runs.
   If you experience problems, check your .env is up to date!

🧭 Implementation

Note: you can probably implement any of these features in any order you choose.

Step 1: Add school profile page link to tooltips

• As you can see on the existing heat map, when you click on a school dot, a tooltip popup is displayed with the name of the school and the count for the currently selected count parameter. Another item we want to add to this tooltip is a link to that school’s school profile page (e.g. /schools/concord-academy). Add this dynamic link to the tooltip.
• For reference, look at the schools table page (/schools) to see how each school name is converted into a route with that school name embedded.
• Another note is that Sprint 5d is working on adding a year selector to each of the school profile pages with the year inputted as a string parameter in the URL. While you won’t be able to link to the school profile page for a specific year just yet until that ticket is completed, make your code easy enough to edit later so that when you click on a link to a school profile from the tooltip, it will take the year from the year selector on the heatmap and pass it as a parameter in the school profile page URL.
• Additionally, modify the tooltip so that when a user clicks on the school pin, the tooltip persists and stays open. The user can click elsewhere on the screen or press Escape to close the tooltip.

Step 2: Export heatmap

• Create a utility function in /lib/ to export the given heat map configuration. Similar to bar and line chart export, you’ll want to capture the current state of the heat map on the user's screen and convert to a downloadable PDF.
• The general process used for exporting a chart is: current svg in browser → HTML canvas element (using html2canvas-pro) → PDF (using jspdf)
• For the heatmap, capture the canvas element using MapLibre’s map.getCanvas().toDataURL() function. See documentation for details. Then, generate the PDF using jspdf (already installed). Make sure to account for canvas dimensions and aspect ratios. Look to the chart export for reference and for PDF styling.
• Create an export hook to keep track of the current export state (loading, success, error). Integrate this with the map page, and add an Export button to the top right corner, similar to the charts page.

Step 3: Modify region borders

• This task is far less coding and more so data point manipulation.
• Currently, the red borders on the heat map are displaying the Massachusetts counties. These borders are defined in src/data/counties.json. Instead, Paula and Elyssa would like them to display regions, which are defined by their own grouping of counties. The groupings of counties into regions are as follows:
  • Western = Berkshire + Franklin + Hampshire + Hampden
  • Central = Worcester
  • Metro Boston = Suffolk
  • Northeast = Middlesex + Essex
  • Southeast = Plymouth + Bristol + Dukes + Norfolk + Barnstable + Nantucket
• We want to preserve any of the county borders that already exist and should remain as outer borders of regions but combine borders that run through the middle of the regions.
• Both central and metro Boston counties should be straightforward. Just rename those counties/regions.
• Note that some counties are disjoint, such as Dukes and Norfolk, and as such have two county regions defined in counties.json. Since a MapRoute connects all data points within a region, this is the only way to display two regions without connecting them with a line. For regions that contain counties that are disjoint, determine an appropriate way to deal with this that looks good visually. As of right now, the regions do not contribute to the functionality of the program and are just for visual display, so do not worry about creating multiple objects for a single region.
• Feel free to rename the file to regions.json as we are no longer displaying counties.

Step 4: Add sharing functionality

• Similar to the bar and line charts, we want to be able to share a link to a heatmap page and preserve the configuration of the map. In order to do this, we will parameterize the settings (counts and years) for the heatmap in the URL.
• This will be achieved by using nuqs, a search parameter state manager. Look to the bar and line charts for reference on implementation.
• Add a share button to the upper right corner of the page, matching the styling and position of the share button on the charts page.

Step 5: Add a loading animation

• It can take a second for the map, border, school pins, and heat layer to load when visiting the map page. Add a responsive loading element to show users that the map is in a loading state. A sensible way to show this would be to add a slight gray overlay to the entire map layer and a spinning buffer wheel animation in the middle. Use a state hook initially set to false to track whether the page is fully loaded and set to true once the data has been returned.

Step 6: Other little things

• Add titles above the counts and year selector with “Counts” and “Year,” respectively. Use the same font size and formatting as the “Measured by” and “Group by” on the charts page.
• Only display school dots if that school has data (non-zero) of the count for the selected year.

🙌 Acceptance Criteria

• Tooltips refined to include link to school profile page
• Links to school profile have been tested with a variety of school names to ensure full compatibility
• Export and share buttons present and both working as expected
• Loading animation provides users with feedback when loading page
• Borders are now displaying regions and not counties
• Data retrieval still works correctly (school counts are fetched, school locations are still accurate)
• UI matches Figma exactly
• Code runs locally without errors and builds successfully
• Merge via PR

⁉️ Questions

If you get stuck or have questions:

• DM Dan or Shayne on Slack
• Come to office hours or ask during a hack night
• Ask questions during team meetings – we’re here to help!

📝 Resources

• Figma
• Tailwind CSS
• shadcn/ui
• npm package manager
• nuqs
• html2canvas
• jspdf
• MapLibre getCanvas()