[Sprint 7a]: Heatmap Finishing Touches 🎨 - Elki & Will

[danglorioso]

💻 Summary

In this sprint, you will add a few more final features to our heatmap to improve its general usability. Notably, you will add a way for users to apply filters, such as gateway schools, and also jump to customized region-specific views.

Goals of this sprint:

• Gain a deeper understanding of the inner workings of the heatmap, specifically in how the heat layer is generated and how the school pins are placed.
• Work with modifying the layout and content of exported PDFs for both the heatmap and charts.

⚙️ Setup

Before starting:

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

🧭 Implementation

Step 1: Study how the heatmap is implemented

• If you haven’t yet worked with the heatmap, take a bit to review the map component.
• Determine how the schools are fetched from the database and then displayed on the map. Trace this flow.
• Check out files like regions.json that define the boundaries of a region. These coordinates may be helpful later when determining the position of an individual region view.

Step 2: Create filters

• Similar to the bar and line charts, we want to be able to apply filters to the data (schools) displayed on the heat map.
• At the top bar above the map, add a filter component to toggle whether gateway schools are displayed exclusively. Refer to the Figma for specification on what this should look like.
• Ensure that the “Counts” and “Year” fields still apply and retrieve the intended data when your filters are applied.
• Already, the heatmap options are parameterized into the URL. Add your filters as parameterized states in the URL. If you haven’t worked with this yet, check out nuqs and the numerous places they’ve already been used in the projects for reference.

Step 3: Add pre-set views

• An important part of the heatmap for Paula & Elyssa is the ability to compare the “heat” portion of the map over multiple years. In order for this to be meaningful, we need a way to create fixed views or window positions so that their images of the map are consistent between exports.
• There should be 6 views total: one for each of the five regions (Western, Central, Metro Boston, Northeast, Southeast) and one for the whole state (the current default view).
• For each of the views, the user should be able to click which view they would like to see and the map window should jump to it. Again, see the Figma for how this component should be styled. You likely will need to determine the coordinates of each of the corners in order to set a window view. Check how the current window view is set upon page load.
• An important note: users should never be locked into this view and unable to move elsewhere about the map. This view should only be a way to help them see the entirety of one specific region in closer detail.

Step 4: Dynamic title

• Similar to the bar and line charts that display a dynamic title describing exactly the configuration of the graph you are looking at, modify the title of the heatmap to give the user more detail of what they are looking at in the map.
• You should add in the region, year, count, and any filters currently being shown on the map. For example, “Heatmap - Teachers in MA (2025)” or “Heatmap - Projects in Western Region (2024)” or “Heatmap - Students at Gateway Schools in Suffolk Region (2022).”
  • Your naming convention does not need to be exactly this, but it should read clearly and succinctly tell the user what they are looking at.
  • Appeal to the naming style used to dynamically generate titles for the bar/line charts for inspiration.
• When you click on a region view, you should update the title with the current region display. It may be challenging to update the region name as the user moves around the map, but if you can find an accurate way to do that, that would be great! Please do put some effort in, though, to figure out if you can achieve this part.
• Add your dynamic title to the exported PDFs.

Step 6: Side quest - titles to chart PDFs

• Now that you’ve added your dynamic title to the heatmap PDF, we also need to add the dynamic titles to the bar/line chart PDF exports.
• The dynamic titles have already been generated for you. All you need to do is add these titles to the body of the PDFs.
• Additionally, you’ll notice that when you click the “Add To” button to add a specific graph to the export cart, the items are titled with their generic titles. Add the dynamic titles here as well. Since this is a smaller space, you may need to truncate or create more succinct titles/abbreviations in this section to describe the chart.
• While you’re at it, check the export date in the PDF. Right now, it is printing a date that is one month back. This should display the date the PDF was generated.

Step 7: Add heatmap to the “Add to” cart export functionality

• Currently, multiple bar and line charts can be exported in a single PDF by using the “Add To” button in the top bar. We want to add heatmaps to this bulk export as well.
• In addition to the “Export” button that already exists, add an “Add to” button next to it that allows you to add the current view of the heatmap to the exported PDF.
• Look at how the “Add to” button works on the charts page to preserve SVGs within the user’s browser session. Notice that if you add a chart to your cart, go to a different page and come back, your cart is still active. We want to preserve this functionality, especially since the charts and heatmap are on different pages.

Step 5: Testing

• For Step 2: Modify the gateway schools in Settings and ensure that these changes are reflected in the heatmap when filtering by gateway schools.
• For Step 3: Ensure that the export feature preserves the map view and appears in the PDF exactly as it does on the web page.
• For Step 6: Ensure that exporting multiple charts to a PDF still works as intended.
• For Step 7: Make sure the single exports still work and that multiple figures of different types (bar/line chart, heatmap) can be exported to the same PDF.

🙌 Acceptance Criteria

• Users can filter by gateway schools (and when selected, only gateway schools are shown)
• Users can jump to a pre-set view of a specific region
• Region view shows the region in its entirely without any sections cutoff
• Dynamic titles are generated for heatmap configuration
• Exported PDFs contain dynamic titles, for both map and charts
• No existing features were broken with these changes.
• 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