MapsGL Layers Provider

The MapsGLLayersProvider is a core component that provides a React-based state management solution for MapsGL weather layers. It creates an abstraction layer between your application and the MapsGL SDK, handling the complexities of layer management, styling, and state synchronization.

Features

Declarative layer management through React context
Automatic handling of weather layers, including composite layers (multiple layers combined into a single layer alias e.g. tropical-cyclones)
Built-in support for layer styling and settings
Integration with the MapsGLTimelineControl for animated layers

Usage

MapsGLLayersProvider must be a child of the MapsGLMapControllerProvider as it consumes the map controller from the MapsGLMapControllerContext to manage layers. The provider is agnostic to the layers UI, maintaining a flat state structure for all layers.

Here's a an example of a basic setup:

import { MapsGLMapControllerProvider, MapsGLLayersProvider } from '@xweather/maps-ui-sdk';
 
// Define the inital layers configuration, set active to true to show the layer on load
const initialState: InitialLayersState = {
    radar: {
        layerId: 'radar',
        weatherId: 'radar',
        active: true,
    },
    // If weatherId is not provided, it will be set to the layerId
    temperatures: {
        layerId: 'temperatures',
        active: false,
    },
    // Multiple layers can have the same weatherId if they need the same underlying weather layer
    temperatures: {
        layerId: 'temperatures-alt', // Make sure to set a unique layerId
        weatherId: 'temperatures',
        active: false,
    },
};
 
function WeatherMap() {
  return (
    <MapsGLMapControllerProvider
      accessKeys={accessKeys}
      strategy="mapbox"
      map={map}
    >
      <MapsGLLayersProvider initialState={initialState}>
        {/* Layer controls consume the layer state through the useMapsGLLayersContext hook */}
      </MapsGLLayersProvider>
    </MapsGLMapControllerProvider>
  );
}

Layer Configuration

When building a UI based on the layer state it's recommended to construct a layersConfig object with the LayersConfig type. This can be used by your ui components to render the layers and as well as passed to the layerStateFromConfig utility to convert the configuration object into the required state structure (InitialLayersState) to be used with the MapsGLLayersProvider.

The configuration supports:

Grouped layers for organization with multiselect option
id, title, value for individual layers (id -> layerId, value -> weatherId when using layerStateFromConfig)
settingsOptions for individual layers
Layer overrides for customization

const layersConfig: LayersConfig = [
  {
    // Simple weather layer
    id: 'radar',
    title: 'Radar',
    selected: true
  },
  {
    // Layer with custom settings
    id: 'temperatures',
    title: 'Temperatures',
    settingsOptions: [
      { name: 'opacity', value: 80 },
      { name: 'sample.colorscale.interval', value: 2 }
    ]
  },
  {
    // Grouped layers
    title: 'Severe',
    group: [
      { id: 'alerts', title: 'Alerts' },
      // Composite layers like tropical cyclones are supported
      { id: 'tropical-cyclones', title: 'Tropical Cyclones' }
    ]
  },
  // Layer with custom overrides
  {
        id: 'fires-custom',
        title: 'Fires: Custom',
        value: {
            id: 'fires-obs',
            overrides: {
                layer: customFiresStyle
            }
 
        }
    }
];

Here is an example of using a layersConfig object to initialize the layer state in the MapsGLLayersProvider as well as render the UI with the MapsGLLayersControl component:

function WeatherMap() {
  return (
    <MapsGLMapControllerProvider
      accessKeys={accessKeys}
      strategy="mapbox"
      map={map}
    >
      <MapsGLLayersProvider initialState={layerStateFromConfig(layersConfig)}>
        <MapsGLLayersControl config={layersConfig} />
      </MapsGLLayersProvider>
    </MapsGLMapControllerProvider>
  );
}

Styling

For detailed information about layer styling options, refer to the MapsGL Styling Documentation (opens in a new tab).

Example of styling a temperature layer when passed directly to the MapsGLLayersProvider:

const initialState: InitialLayersState = {
  temperatures: {
    active: true,
    settings: {
      'opacity': 0.8,
      'sample.colorscale': {
        stops: [-20, '#0000ff', 0, '#ffffff', 20, '#ff0000'],
        interpolate: true
      }
    }
  }
};

Example of styling a temperature layer when passed through the layersConfig object:

const layersConfig: LayersConfig = [
  {
    id: 'temperatures',
    title: 'Temperatures',
    settingsOptions: [
      'opacity', // Will update the opacity default setting
      { 
        name: 'sample.colorscale', 
        value: { 
            stops: [-20, '#0000ff', 0, '#ffffff', 20, '#ff0000'], 
            interpolate: true 
        } 
      }
    ]
  }
];

API Reference

MapsGLLayersProvider

Option	Description	Default
`children`	Type: `ReactNode` (required)Child components
`initialState`	Type: `InitialLayersState` (required)Initial configuration for layers

MapsGLLayersContext

The provider exposes the following context through useMapsGLLayersContext:

Name	Type	Description
`layers`	`LayersState`	Current state of all managed layers
`addLayer`	`(layerId: string) => void`	Adds a layer to the map
`removeLayer`	`(layerId: string) => void`	Removes a layer from the map
`toggleLayer`	`(layerId: string) => void`	Toggles layer visibility
`updateLayerSetting`	`(layerId: string, setting: ValuePayload) => void`	Updates layer settings

Types

LayerState is used to define the individual layer state when consumed through the useMapsGLLayersContext hook:

interface LayerState {
  layerId: string; // Unique identifier for the layer
  weatherId: string; // Underlying MapsGL weather layer identifier
  active: boolean; // Current visibility state
  settings?: LayerSettings; // Layer-specific settings
  overrides?: LayerOverrides; // Custom layer configurations
}

InitialLayerState is used to define the initial layer state passed to the MapsGLLayersProvider. Here layerId and weatherId are optional as they can be derived from the layer state key in the InitialLayersState object:

interface InitialLayerState extends Omit<LayerState, 'layerId' | 'weatherId'> {
    layerId?: string;
    weatherId?: string;
}
 
interface InitialLayersState {
    [key: string]: InitialLayerState;
}
 
interface MapsGLLayersProviderProps {
    children: ReactNode;
    initialState: InitialLayersState;
}

LayersConfig is used to define the layer UI configuration object.

interface LayerOverrides {
    beforeId?: string;
    layer?: Partial<WeatherLayerOptions>;
}
 
type LayerButtonOptionSetting = string | ControlSetting | Partial<ControlSetting>;
 
interface LayerButtonOptions {
    id: string;
    title: string;
    selected?: boolean;
    settingsOptions?: LayerButtonOptionSetting[];
    value?: string | {
        id: string;
        overrides: LayerOverrides;
    };
}
 
interface LayerButtonSegmentOptions extends LayerButtonOptions {
    multiselect?: boolean;
}
 
interface LayerSegmentedButtonOptions extends Omit <LayerButtonOptions, 'value'> {
    options: LayerButtonSegmentOptions[];
    selected?: boolean;
    multiselect?: boolean;
}
 
interface LayerButtonGroupOptions {
    id?: string;
    title: string;
    multiselect?: boolean;
    group: (LayerButtonOptions | LayerSegmentedButtonOptions)[];
}
 
type LayersConfigItem = LayerButtonGroupOptions | LayerButtonOptions |  LayerSegmentedButtonOptions;
 
type LayersConfig = LayersConfigItem[];

Map Controller Provider Layers Control