@xweather/map-ui-sdk

map-ui-sdk

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.

Supported Mapping Libraries

Map UI SDK currently supports the third-party mapping libraries supported by MapsGL

Getting Started

yarn add @xweather/map-ui-sdk@alpha

Example Project

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:

Prerequisites

• An Xweather account— We offer a free developer account for you to give our weather API a test drive.
• A Mapbox account

Steps to Run

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

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

3. Navigate to the Example Directory After downloading or cloning map-ui-sdk from npm, navigate to the example directory within the SDK:

> cd ./example

4. Install Dependencies Once you're in the example directory, install the project's dependencies by running:

> yarn install

5. 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=''

6. Import styles You will need to import this stylesheet at the root of your project: import '@xweather/map-ui-sdk/dist/style.css'

7. Run the project in development mode:

> yarn dev

Exploring the Example Project

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.

Usage

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.

MapsGL Resources

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:

• Getting started
• MapsGL Documentation
• Demos: Media, Severe
• Examples

Support

For all MapsGL-specific support, submit a new ticket with any questions, bug reports or feature suggestions you have.