Management of layout through state

[TangoYankee]

The Capital Planning map has components to manage information on the screen.

These components are broadly:

1. Welcome Information Panel
2. Geography Filter Button
3. Geography Selector Panel
4. Project Information Panel
   • List of projects
   • Individual project
   • Commitments for a project
   • Data Export Modal

The behavior of these components differs between mobile and desktop. Desktop allows almost all of them to appear simultaneously. Mobile only shows one component at a time but offers the option to navigate back to a previous component. In the mobile scenario, the components need a way to "know" about each other and the previous states of the layout. In these scenarios, a higher-level state manager can hold this information in a central location and make it easier to reason about. In the case of Capital Planning map, we are using Remix which has a robust routing system that can hold the state of the system. Because it hooks into the browser's routing API, we also get access to the history API and a "free" state stack that we can navigate through. Although, not of all the components can be mapped directly to a route. The welcome panel can appear on any route with the desktop version. However, it can only appear on the base route of the mobile version. To reflect this, we will need a state management paradigm that is decoupled from the URL paths. This could be either in-memory or embedded in a query parameter. We can decide which works best with the overall architecture as we get more details. For now, it is referred to generically as "component layout sets"

Before we start writing components, we should design this state management system. The components can then more easily fit within the context of this system.

Visual representation

Figma Wireframes

URLs:

The URLs manage the "macro state" of the layout. Each URL corresponds to

Root

/

Community Districts

Geography Selection

/community-districts

Geography Selection: Borough Selected

/community-districts/{boroughId}

Geography Selection: Borough and Community District Selected

/community-districts/{boroughId}/{communityDistrictId}

Capital Projects Panel: Show list of projects

/community-districts/{boroughId}/{communityDistrictId/capital-projects

Capital Projects Panel: Show details of a specific project

/community-districts/{boroughId}/{communityDistrictId/capital-projects/{capitalProjectId}

Capital Projects Panel: Show commitment details for a project

/community-districts/{boroughId}/{communityDistrictId/capital-projects/{capitalProjectId}/commitments

City Council Districts

Geometry selection

/city-council-districts

Geometry Selection: CCD selected

/city-council-districts/{cityCouncilDistrictId}

Capital Projects Panel: Show list of projects

/city-council-districts/{cityCouncilDistrictId}/capital-projects

Capital Projects Panel: Show details of a specific project

/city-council-districts/{cityCouncilDistrictId}/capital-projects/{capitalProjectId}

Capital Projects Panel: Show commitment details for a project

/city-council-districts/{cityCouncilDistrictId}/capital-projects/{capitalProjectId}/commitments

Component Layout Sets

default

• Mobile:
  • Welcome Panel (only on root path)
  • Geography Selector Button (only on root path)
• Desktop
  • Welcome Panel
  • Geography Selector

sparse

• Mobile
  • Geography Selector Button (only on root path)
• Desktop
  • Geography Selector

geographySelector

• Mobile
  • Geography Selector
• Desktop
  • Geography Selector

Component behavior

Welcome Panel

Mobile

• On root route: visible on default layout set
• Any other route: hidden regardless of layout set

Desktop

• Visible on default layout set, without regard to route
• Hidden on sparse and geography selector layout sets, without regard to route

Geography Filter Button

Mobile

• Visible on the sparse and default layout set on root route
• Hidden on the geographySelector layout sets on root route

Desktop

• Hidden on all routes and layout sets

Geography Selector Panel

Mobile

• Visible on geographySelector layout set on the root route
• Visible on "Geography Selection" routes
• Hidden on default and sparse layout sets on the root route

Desktop

• Visible on all routes and layout sets

Project Information Panels

Mobile and Desktop

• Visible when, and only when, on the corresponding "Capital Projects Panel" route is active
• Note: The date export panel is defined as part of its project information panel, merely using a "portal" to appear like a separate component

User-driven state changes

Now that we have defined the states and their associated layouts, we can discuss how to move between different states.

On page load

• root route
• default layout set

Clicking the welcome Information Panel

• stay on root
• change to sparse layout set

Clicking the Geography Filter Button

• stay on root
• change to geographySelector layout set

Selecting a geography in the first dropdown of the Geography Selector Panel

• navigate to the corresponding geography route ie) community-districts

Selecting a specific geography in the Geography Selector Panel

• navigate to the corresponding specific geography route ie) community-districts/boroughId/communityDistrictId
• For city council districts, there is only one field to select
• For community districts, there are two fields to select (borough and community district id). The route updates at each selection then

Clicking "Go to Selected Geography"

• navigate to the projects list route for the geography

Clicking on a specific project

• navigate to the project details route

Clicking on the commitments dropdown

• navigate to the commitments route

Toggling the commitments closed

• navigate back to the project details route

Clicking on the Mobile Project Information Back button

• navigate to previous route

Clicking on the Desktop Project Information Close button

• navigate to the current geography route, as if the route was truncated to only specify the ccd or cd

[TylerMatteo]

@TangoYankee Thanks for putting this together. Some of this will probably be easiest to talk through with James but let me share some immediate reactions to what you have above.

Note: The date export panel is defined as part of its project information panel, merely using a "portal" to appear like a separate component

Correct. We can use Chakra's modal for this, which in turn is using a portal. I have a draft issue to passthrough the modal component in Streetscape. I don't think the expectation is that the modal being opened or closed would be reflected in the URL.

Capital Projects Panel: Show commitment details for a project

/community-districts/{boroughId}/{communityDistrictId/capital-projects/{capitalProjectId}/commitments

I was thinking the commitments would just be loaded for the capital project route and the state for toggling the accordion would be handled locally, defaulting to closed, but we could get James' take on this. It's simple enough from a routing perspective and there is some value to "lazy loading" the commitments.

[TangoYankee]

It's simple enough from a routing perspective and there is some value to "lazy loading" the commitments.

And the endpoints are organized to support lazy loading. The first endpoint supplies all the information required for the capital project details. The second endpoint supplies the commitment information.

[TylerMatteo]

Route for viewing a project selected directly from the map

There may be an argument for having a /capital-projects/{capitalProjectId} path in addition to the geography-nested ones you have above. The use case for this is when a user selects a project directly from the map. /capital-projects/{capitalProjectId} gives us a path that tells the state that it should show the information for a project, but that the geography filter should be empty and the geography outline layers on the map shouldn't be visible.

[TangoYankee]

Yes, that makes sense

[TangoYankee]

Reading these back, I'm reminded that {capitalProjectId} is truly {managingCode}/{capitalProjectId}

[TylerMatteo]

@TangoYankee It seems like a lot of the complexity comes from how to best handle the geography filter menu with routing. I'm going to describe one potential solution here, feel free to poke holes. It may be easier to talk through it IRL so I'm happy to do that as well.

1. Have the geo menu and the "Filter by Geography" button be a part of the root route's component. Toggling between the menu and the "Filter by Geography" button would be handled by a combination of conditional JSX based on screen size and client-side state (could just be a simple boolean useState). The client side state would show/hide it on mobile and the conditional JSX could effectively "override" that boolean to always show it on desktop.
2. Keeping track of the selected geography type, borough, and district - Maybe it would be best to handle these with query parameters instead of route segments? That way we could keep track of their values on mobile and "remember" them even when the filter menu is hidden.

I'll take a swing at implementing this and see how far I get. If nothing else, it'll be a good chance for me to get some familiarity with Remix's router.

[TangoYankee]

The complexity stems from the combinatorics of layout states. Query parameters and JSX conditions are merely tools to express these states. The top-level comment attempts to use path parameters to organize the combination of layout states into a comprehensive framework. Query parameters and JSX conditionals could also be used for such a framework. But, I would need to see that framework described before I am able to analyze it.

[TylerMatteo]

@TangoYankee The details here in combination with the Figma are looking good. I created a milestone to group together Issues related to front end implementation. While I'm out, try to work with folks as they are picked up to incorporate the routing requirements into the AC where relevant.