Improve user interface design; add new metrics and charts; refactor frontend components

[youngj]

This pull request updates several parts of the user interface to fix various usability issues. It also adds new metrics and charts that were already returned by the GraphQL API but not yet displayed, including comparing observed and scheduled metrics. It also refactors the code for many of the frontend components, making it easier to add charts and reorganize the user interface in the future.

The design changes are described in https://docs.google.com/document/d/1RpVZsbBHFiPLXbKcmsa4gi68ab-C_yi1Ar3lHshu6i4/edit# . This document includes detailed descriptions of usability issues that were identified with the current design, as well as the proposed user interface changes. Please review this document and feel free to add comments.

With input from several people at Code for PDX, I also drafted a more general document proposing design principles for OpenTransit that all contributors could refer to when considering design changes in the future: https://docs.google.com/document/d/19soN0I69lygHuQbKbWlx7OKgHOek38MU2eMS0y3rH1s/edit# . Since OpenTransit has a growing number of contributors in multiple cities, agreeing on shared design principles would help ensure that teams in different cities can continue to benefit from each other’s work, without needing to fork the codebase and work on changes on their own.

The TriMet version of the app with these changes can be seen at http://opentransit-youngj.herokuapp.com/ .

In the process of implementing these user interface design changes, a lot of the frontend code was refactored as well.

• Moved the main navigation bar into the App component, to avoid duplicating navigation UI components in every screen.
• Created a SimpleChart component, a wrapper around react-vis XYPlot, to make it easier to create charts with crosshairs (tooltips showing the values at the mouse cursor) and appropriately formatted axis labels, ticks, and legends, with a consistent UI with much less code. The react-vis library provides low-level functionality which previously required a lot of tedious duplicative code for each chart, such as managing the state to keep track of which data point the mouse is currently over. Most of the existing charts were refactored to use SimpleLineMarkChart, SimpleVerticalBarChart, or SimpleVerticalRectChart, and several new charts were implemented: OnTimePerformanceByDayChart, OnTimePerformanceByTimeChart, OnTimePerformanceHistogram, ServiceFrequencyByDayChart, ServiceFrequencyByTimeChart, and ServiceFrequencyGapHistogram.
• Each chart is refactored into its own component, which is connected to the redux state. This allows the screens that display charts to render each chart like without needing to pass props to each chart, and simplifies the code by avoiding mixing logic for several charts in one screen. This will make it easier to rearrange charts and screens in the future, and make it easier to customize which charts are displayed via configuration. If a chart is not applicable for the current graphParams, it will render as empty. This lets the parent screen not need to know the conditions when each chart is displayed.
• Updated most charts to support comparing observed vs scheduled metrics, and comparing metrics from two date ranges.
• Previously, the x-axis labels for "By Day" charts were shown for each date, which made it necessary to render each date vertically to avoid overlap. Now, the x-value is set to the index of the date, which allows react-vis to avoid showing every date label on the x-axis.
• Renamed components with names starting with "Info" to more appropriate names.
• Used GraphQL @include directives to avoid creating separate queries for single/dual date ranges, and avoid fetching timeRanges field when the time range is not "All Day"
• Added updateQuery action to simplify logic in date/time range controls. To change the query string while keeping the rest of the URL the same, it calls dispatch with the type set to state.location.type, and payload set to state.location.payload. (It isn't necessary to look up the type from state.page, since the type is already part of the state.)
• The RouteSummary component now only shows data from state.routeMetrics, instead of combining data from state.agencyMetrics and state.routeMetrics. In the future, when the user changes the date range, we could avoid making the API request to update state.agencyMetrics unless the user is viewing the Dashboard.
• Split the content of each RouteScreen tab into separate components (e.g. OnTimePerformanceStats, ServiceFrequencyStats)
• Tabs in the RouteScreen component are refactored so that each tab and its associated component are defined only in one place. This would make it easier to customize the RouteScreen tabs in the future via configuration.
• When a RouteScreen tab is not active, its content is no longer rendered. Previously, inactive tabs were rendered but the associated content was set as hidden.

We have already been discussing these changes over the past few weeks in Portland. I'd expect that there may also be consensus support in SF for many of these changes, but some contributors in SF may not agree with some of these proposed changes, such as the removal of scores, stars, colored chips, cards, and certain metrics. However, we would support changes that allow SF to customize the UI via configuration, e.g. if SF still wants to display scores.

Since these changes involve significant refactoring that will result in many merge conflicts as other developers make frontend changes, I would recommend merging these changes relatively quickly and creating issues in GitHub for non-trivial fixes. If the SF team still wants to show scores, stars, cards, etc, I would suggest making this functionality available via configuration options after the changes are merged.

Fixes #590. Fixes #582. Fixes #554. Fixes #545. Fixes #543. Fixes #542. Fixes #438. Fixes #394. Fixes #246. Fixed #620.

[hathix]

A doozy! Great bundle of usability improvements, and I'm glad we have a more fleshed-out design framework. Comments:

• I don't worry too much about removing the scores as long as we address #553 at some point, which would let us bring back the score if desired.
• However, the color coding is a useful way to let people skim and extract key information at a glance. I would support a PR that lets teams add that back if desired. But, as you said, merging this quickly is important, and I think your PR is generally 80+% of the way there, so the best move would be to merge this and file a bunch of issues afterward.
• Refactors look fine to me, though Terence/Arun/others are better qualified to speak about it.
• re: moving isochrone/about from hamburger menu to header: not bad, but I worry that it may not scale well as we add more tabs. Perhaps just getting rid of the icon labels is enough.
• I assume the homepage would be fleshed out, instead of being a few blue links and text. Busstat.nyc had a handy homepage that we could use.
• These touch handles (the plus / X) are pretty small; I would suggest having bigger ones

• Also, on that view, the fields move a lot when I select something on the dropdown. A bit disorienting. I see how it is compact, but I would prefer if the controls were spread out across the page at the start so they didn't constantly shuffle around whenever I picked something. The Grid View may be of use?
• On the Marey chart view, the left and right side of the screen don't scroll together. Should we change that?
• When I choose 2 date ranges, the comparison table goes from observed vs scheduled to observed vs observed. Makes sense, but was jarring at first. An icon to call out more explicitly that the table is showing different kind of data from before would help.
• This might be a backend thing, but the sorting here is busted:

• The new design guide talks a lot about how the table on the metrics homepage is explicitly about the observed data without any kind of value judgment, but I think users would like to see the comparison to the schedule at a glance too. A switch on that page that lets users see comparisons to the schedule (like, turn all the numbers into +/- percentages showing the observed vs schedule data) would be useful. Obviously a big feature, and would belong in a new issue.
• It took me a second to figure out what the green numbers ("26 min shorter", etc) meant on this view. Perhaps add something that notes that these numbers compare Right vs Left, or add some visual styling that more closely associates the green numbers with the 2nd date range data. For instance, the "37 min" could say "37 min (26 shorter)".

• Contextual hints on error messages would be useful. For instance, here, it would be nice to have a blue link in the error text that, when clicked, removes the second date.

• Same here.

• Nit, but it's unclear whether this arrow belongs to the Route or Median Service Frequency columns.

• The About page could use some links to our GitHub, the project page, the Code for America pages, etc.
• Seems that this new version doesn't change the <title> at all, whereas the old version did.

[hathix]

Oops, accidentally closed

[hathix]

There are a bunch of other little things, but overall, I like the new direction and the effort that the PDX team has put in. I'm not qualified to review all the actual code, but functionality and design wise, this is a strong start. We may need to file a bunch of issues once this is merged, but that's fine.

I would ask some of the frontend engineers to give the code a proper review before approving.

[youngj]

re: moving isochrone/about from hamburger menu to header: not bad, but I worry that it may not scale well as we add more tabs. Perhaps just getting rid of the icon labels is enough.

Agreed -- this potential issue is noted in the Google doc: "Replaced hamburger menu with 3 tabs on right side of toolbar, so users can easily discover them and switch in one click. Text labels are hidden on small screen widths. With this design, we could probably add 1 more tab in the toolbar if needed. If we need to add more tabs in the future, could switch to a drawer on the left side of the screen, although for now using this unused space in the top-right of the toolbar allows more horizontal space for content."

I assume the homepage would be fleshed out, instead of being a few blue links and text. Busstat.nyc had a handy homepage that we could use.

Yeah, the home page content is just a placeholder. This could be something to work on next.

These touch handles (the plus / X) are pretty small; I would suggest having bigger ones

I agree. The handles are the same size as the inline field labels. Could increase the text size a bit.

Also, on that view, the fields move a lot when I select something on the dropdown. A bit disorienting. I see how it is compact, but I would prefer if the controls were spread out across the page at the start so they didn't constantly shuffle around whenever I picked something. The Grid View may be of use?

This inline layout allows the route, direction, origin stop, destination stop, and date-time range controls to fit on one row of a typical laptop screen for typical route/direction/stop names. We don't know how long each of the text values of each field will be (route/direction/stop names are sometimes quite long), so if the components are not allowed to move then it would likely require two rows of controls, which reduces the screen space for statistics without scrolling. For me, it doesn't seem disorienting for the subsequent fields to move when you change the selection of a previous field. A lot of the page content changes at the same time.

On the Marey chart view, the left and right side of the screen don't scroll together. Should we change that?

They do both scroll together. Are you referring to the map not having a fixed position? In order for the map on the route screen to have a fixed position, we would probably need to make everything above it including the tabs and dropdown controls have a fixed position too.

When I choose 2 date ranges, the comparison table goes from observed vs scheduled to observed vs observed. Makes sense, but was jarring at first. An icon to call out more explicitly that the table is showing different kind of data from before would help.

Could you give an example of what you mean by an icon? I think the heading text and chart legends are pretty clear about what data is being shown.

This might be a backend thing, but the sorting here is busted:

Not sure how to reproduce this, it works for me.

The new design guide talks a lot about how the table on the metrics homepage is explicitly about the observed data without any kind of value judgment, but I think users would like to see the comparison to the schedule at a glance too. A switch on that page that lets users see comparisons to the schedule (like, turn all the numbers into +/- percentages showing the observed vs schedule data) would be useful. Obviously a big feature, and would belong in a new issue.

Agreed, it would be useful to compare observed/scheduled metrics in the routes table somehow. From the Google doc: "In the future, we may want to allow users to compare both observed and scheduled metrics in the same table. There would probably be too many columns if we displayed all observed and scheduled metrics at once, but could have a dropdown that allows you to select one metric at a time (e.g. Median Service Frequency) and shows Observed/Scheduled columns just for that metric. The same approach could work for comparing a metric for multiple date ranges."

It took me a second to figure out what the green numbers ("26 min shorter", etc) meant on this view. Perhaps add something that notes that these numbers compare Right vs Left, or add some visual styling that more closely associates the green numbers with the 2nd date range data. For instance, the "37 min" could say "37 min (26 shorter)".

I'm open to different ways of presenting this data. Maybe saying "26 min shorter" in text isn't really necessary.

Contextual hints on error messages would be useful. For instance, here, it would be nice to have a blue link in the error text that, when clicked, removes the second date.

Sounds good to me.

Nit, but it's unclear whether this arrow belongs to the Route or Median Service Frequency columns.

The arrows are on the left side of right-aligned columns (not changed in this PR). I think users will understand because the arrow changes when they click on the column header.

The About page could use some links to our GitHub, the project page, the Code for America pages, etc.

Sounds good to me, this content is just a placeholder.

Seems that this new version doesn't change the