Maps UI SDK - Settings Provider

A context provider for managing application-wide settings across your application.

Usage

The SettingsProvider must wrap any components that need access to unit settings or color scales. This includes:

MapsGLLayersProvider and its children
MapsGLLayersControl
Components using layer control hooks (useLayersControl, useLayerControl, useLayerGroupControl)
Components that display units (e.g., built-in data views/cards like ConditionsCard)


import { 
    SettingsProvider, 
    MapsGLLayersProvider, 
    MapsGLLayersControl 
} from '@xweather/maps-ui-sdk';
 
const { temperature, speed } = UNITS;
 
const initialSettings = {
    unitSystem: 'metric',
    units: {
        temperature: temperature.C,
        speed: speed.kmh
    }
};
 
export default function App() {
    return (
        <SettingsProvider initialSettings={initialSettings}>
            <MapsGLLayersProvider>
                <MapsGLLayersControl />
                {/* Other components that need access to settings */}
            </MapsGLLayersProvider>
        </SettingsProvider>
    );
}

The provider manages:

Unit system (metric/imperial) and individual unit settings
Color scales for layer styling
Other application-wide settings

Initial Settings

You can configure the initial settings through the initialSettings prop:


interface InitialSettings {
    unitSystem?: 'metric' | 'imperial' | null;
    units?: Partial<Record<MeasurementType, Unit>>;
    colorScales?: Record<string, ColorScaleOptions>;
    // Additional custom settings
    [key: string]: any;
}

If no unit system is specified, it defaults to imperial units.

API reference

SettingsProvider

The main provider component that wraps your application to provide settings functionality.

Option	Description	Default
`children`	Type: `ReactNode` (required)The child components that will have access to the settings context.
`initialSettings`	Type: `InitialSettings` (optional)The initial settings for the application.

useSettingsContext

A custom hook to access the settings context within child components.

Returns an object with the following properties:

Name	Type	Description
`units`	`Record<MeasurementType, Unit>`	The current units for different measurement types.
`unitSystem`	`UnitSystem \| 'custom'`	The current unit system.
`colorScales`	`Record<string, ColorScaleOptions> \| undefined`	The color scales for the application.
`[key: string]`	`string \| number \| Record<string, unknown> \| Record<string, ColorScaleOptions> \| undefined \| null`	Any additional custom settings.

Types

InitialSettings

The structure for initial settings.


type InitialSettings = Omit<Partial<SettingsContextProps>, 'units'> & {
  unitSystem?: UnitSystem | null,
  units?: Partial<Record<MeasurementType, Unit>>;
  colorScales?: Record<string, ColorScaleOptions>
};

UnitSystem

The possible unit systems.


type UnitSystem = 'imperial' | 'metric';

MeasurementType

The types of measurements available.


type MeasurementType = 'temperature' | 'speed' | 'pressure' | 'height' | 'distance' | 'precipitation' | 'snowfall' | 'direction' | 'time' | 'rate' | 'concentration' | 'ratio';