map-ui-sdk is an alpha-stage UI toolkit, built with React and TypeScript, aimed at enhancing mapping interfaces with interactive UI panels integrated with our MapsGL service. Currently it offers a control for managing map layer visibility and styling as well as a timeline control for easily manipulating and animating the time range data for the map.
Map UI SDK currently supports the third-party mapping libraries supported by MapsGL
yarn add @xweather/map-ui-sdk@alpha
map-ui-sdk includes an example project that demonstrates how to use the SDK with a mapping library. The example project is located in the example
directory, separate from the SDK implementation code. Follow the steps below to get the example project up and running:
- An Xweather account— We offer a free developer account for you to give our weather API a test drive.
- A Mapbox account
-
Get Xweather MapsGL ID and Secret Log into your Xweather account, and from your account's Apps page, create a new application for the MapsGL Demo app. Make note of application's Xweather MapsGL ID and Secret; you'll need them in step 5.
-
Get Xweather Mapbox public access token The example project relies on Mapbox, so you'll need to log into or create a Mapbox account and follow the instructions to create a Mapbox public access token.
-
Navigate to the Example Directory After downloading or cloning map-ui-sdk from npm, navigate to the
example
directory within the SDK:
> cd ./example
-
Install Dependencies
Once you're in the
example
directory, install the project's dependencies by running:
> yarn install
- Update environment variables Rename .env.template at the root of the example repo to .env and add the necessary Xweather and Mapbox access key:
VITE_MAPBOX_KEY=''
VITE_MAPSGL_ID=''
VITE_MAPSGL_SECRET=''
-
Import styles You will need to import this stylesheet at the root of your project:
import '@xweather/map-ui-sdk/dist/style.css'
-
Run the project in development mode:
> yarn dev
This project demonstrates an example configuration of the <LayersPanel/>
which offers the ability to customize which layers are displayed and how they are styled through the layersConfig
prop.
layerConfig
example:
import {SAMPLE,COLOR_SCALE, DATA, ButtonListConfig} from '@xweather/map-ui-sdk';
const layersConfig: ButtonListConfig = [{
title: 'Conditions',
buttons: [
{
id: 'temperatures',
title: 'Temperatures',
value: 'temperatures',
selected: false,
controls: {
settings: [
{
name: SAMPLE.opacity,
overrides: {
value: 90
}
},
COLOR_SCALE,
SAMPLE.colorscale.interval,
DATA.quality
]
}
},
{
id: 'wind',
title: 'Winds',
selected: false,
multiselect: false,
segments: [{
id: 'wind-barbs',
title: 'Barbs',
value: 'wind-barbs',
controls: {
settings: [
GRID.spacing,
SYMBOL.size
]
}
},
{
id: 'wind-particles',
title: 'Particles',
value: 'wind-particles',
controls: {
settings: [
COLOR_SCALE,
SAMPLE.smoothing,
PARTICLE.speed,
PARTICLE.size,
PARTICLE.density,
DATA.quality
]
}
}, {
id: 'wind-speeds',
title: 'Fill',
value: 'wind-speeds'
}]
}
]
}];
map-ui-sdk implements the Provider pattern to facilitate data sharing and state management across UI components allowing for increased component reusability. In order to use MapsGL-specific layers, simply wrap the <LayersPanel/>
in <MapsGLLayerStateProvider />
(provide its initial state; the same layersConfig
passed to the <LayersPanel/>
), and MapController
. By also utilizing the Drawer
and Tabs
components, you can quickly build an interface for mapping layer interactions.
Below is a simplified version to show the basic component structure, review App.jsx
in the example project for the full implementation:
<MapController>
<MapsGLLayerStateProvider initialState={layersConfig}>
<DrawerProvider>
<TabsProvider defaultValue="layers">
<Drawer>
<Tabs.Content value="layers">
<LayersPanel layersConfig={layersConfig} />
</Tabs.Content>
<Tabs.Content value="settings">
<SettingsPanel />
</Tabs.Content>
<Tabs.List>
<Tabs.Button value="layers" />
<Tabs.Button value="settings" />
</Tabs.List>
</Drawer>
</TabsProvider>
</DrawerProvider>
</MapsGLLayerStateProvider>
</MapController>
Additionally, the example project demonstrates the <MapsGLTimelinePanel />
which wraps the TimelinePanel
and encapsulates the MapsGL integration, allowing for easy animation control of mapping layers. Included in the TimelinePanel
is a settings button that enables on-the-fly configuration of the time range as well as the speed of animation. Any layers that are currently selected in the layers panel and have animation capability will respond to the TimelinePanel
controls.
Since map-ui-sdk is written in TypeScript you can refer to the .d.ts
declaration files in the dist
folder for comprehensive type definitions. These mirror the SDK's structure offering insights into component interfaces and configurations. In particular the <LayersPanel />
and <TimelinePanel />
types can be found inside the dist/views
and the various providers are located inside dist/providers
.
Use the following resources to learn more about MapsGL and the wide range of customization options, or to view a variety of demos and examples:
For all MapsGL-specific support, submit a new ticket with any questions, bug reports or feature suggestions you have.