@hyperobjekt/react-dashboard NPM

@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.