@hyperobjekt/react-dashboard

This package provides base configuration for a dashboard and hooks for:

• Configuration loading and retrieval based on current context
• Formatters for different data types
• Hooks to provide data to components (for Maps, Controls, Location Data, etc.)
• i18n
• State management (via zustand)
• Query Param Routing

Running the demo

Clone this repo, then run yarn install and yarn dev to run the demo.

Code for the demo is in the /demo directory.

Getting Started

This library contains no UI elements. You provide a configuration to the dashboard, and then you utilize the available hooks to provide data to your components.

// see the configuration documentation below for more details
const DASHBOARD_CONFIG = {
  "app": { ... },
  "metrics": [ ... ],
  "regions": [ ... ],
  "subgroups": [ ... ],
  "scales": [ ... ],
  "mapSources": [ ... ],
  "mapLayers": [ ... ],
  "lang": { ... }
}

const MyDashboardApp = () => {
  return (
    <Dashboard config={DASHBOARD_CONFIG}>
      {/* Your UI components here */}
    </Dashboard>
  )
}

You can then use the dashboard hooks in your app as needed.

Context Hooks

• useBubbleContext() => {metric_id, region_id, subgroup_id, year }
  • returns current context for the bubble metric
• useBubbleVarName() => string
  • returns the current bubble metric variable name (based on accessor config and current context)
• useChoroplethContext() => { metric_id, region_id, subgroup_id, year }
  • returns the current context for the choropleth metric
• useChoroplethVarName() => string
  • returns the current choropleth metric variable name (based on accessor config and current context)
• useCurrentContext() => { bubbleMetric, choroplethMetric, region_id, subgroup_id, year }
  • returns the current context of the dashboard state, including both bubble and choropleth metrics

Metric Hooks

• useMetricConfig(id:string || [id:string])
  • returns metric configuration, with populated names, hints, units, and formatters. Returns all if no argument is provided, a single metric if an ID is passed, or a subset if an array of IDs is passed.
• useBubbleOptions()
  • returns an array of bubble metric options with names, hints, units, and formatters.
• useChoroplethOptions()
  • returns an array of choropleth metric options with names, hints, units, and formatters.

Region Hooks

• useRegionOptions()
  • returns an array of region options with names

Subgroup Hooks

• useSubgroupOptions()
  • returns an array of subgroup options with names

Year Hooks

• useYearOptions()
  • returns an array of year options

Scale Hooks

• useScaleConfig(context)
  • returns a scale in the configuration that matches the provided context
• useChoroplethScale({context?, config?})
  • returns scale functions and props for Scale components for a choropleth metric. Optional context overrides and scale config overrides.
• useBubbleScale({context?, config?})
  • returns scale functions and props for Scale components for a bubble metric. Optional context overrides and scale config overrides.

Map Hooks

• useMapSources()
  • returns map sources for the current context
• useChoroplethMapLayers()
  • returns choropleth map layers for the current context
• useBubbleMapLayers()
  • returns bubble map layers for the current context

Location Hooks

• useAddLocation()
  • returns a function that can be used to add a location feature to the selected locations store
• useRemoveLocation()
  • returns a function that can be used to remove a location feature from the selected locations store
• useLocationFeature(string || number)
  • returns all selected location features if no argument is provided, or a single location if an ID is passed, or the n most recent locations if a number is passed
• useLocationData(string || number)
  • returns all selected locations data (feature.properties) if no argument is provided, or a single location if an ID is passed, or the n most recent locations if a number is passed

State Store Hooks

All of the above hooks use these state stores as their source of truth. These hooks are all zustand stores that are used by the dashboard. See the zustand recipes for how to select the state slices you need.

• useDashboardStore()
  • contains dashboard state and setters for bubbleMetric, choroplethMetric, region, year, subgroup.
• useLocationStore()
  • contains location state for selected locations
• useConfigStore()
  • contains configuration state and setters for app, metrics, regions, subgroups, scales, mapSources, mapLayers, and ready state.
• useRouteStore()
  • contains router state and setters for varMap and queryParams
• useMapStore():
  • contains all relate map state and setters
  • this store should be imported from @hyperobjekt/mapgl and is not part of @hyperobjekt/react-dashboard. See documentation in the mapgl repo for this store.

Data fetching hooks

The base dashboard component is a QueryProvider from react-query. You can use useQuery and any other react-query hooks within the <Dashboard /> scope.

Additional Docs

More documentation can be found in their specific module folder:

• Config: README
• i18n: README | API
• Router: README | API
• Formatters: README | API
• Locations: README | API

The following libraries are utilized or intended to be used with this project:

• react-query
• zustand
• @hyperobjekt/mapgl
  • react-map-gl (foundation for @hyperobjekt/mapgl)
• @hyperobjekt/scales