@carto/kepler.gl 0.0.80 → 0.1.0-alpha.0

package/src/actions/actions.ts

@@ -0,0 +1,259 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import ActionTypes from 'constants/action-types';
+import {createAction} from '@reduxjs/toolkit';
+
+import {ParsedConfig} from '../schemas';
+import {RGBColor} from 'reducers/types';
+import {Bounds} from 'reducers/map-state-updaters';
+import {MapInfo} from 'reducers/vis-state-updaters';
+import {UiState} from 'reducers/ui-state-updaters';
+
+/**
+ * Input dataest parsed to addDataToMap
+ */
+export type ProtoDataset = {
+  info: {
+    id?: string;
+    label?: string;
+    format?: string;
+    color?: RGBColor;
+  };
+  data: {
+    fields: {
+      name: string;
+      type?: string;
+      format?: string;
+      displayName?: string;
+      id?: string;
+    }[];
+    rows: any[][];
+  };
+
+  // table-injected metadata
+  metadata?: any;
+  supportedFilterTypes?: string[];
+};
+
+export type AddDataToMapOptions = {
+  centerMap?: boolean;
+  readOnly?: boolean;
+  keepExistingConfig?: boolean;
+  autoCreateLayers?: boolean;
+};
+
+export type AddDataToMapPayload = {
+  // TODO/ib - internally the code calls `toArray` a couple of layers deep
+  // so this function can actually accept both an array and an object
+  // recommend dropping such "sloppy typing" and enforcing array type
+  // as the field is called `datasets`
+  datasets: ProtoDataset[] | ProtoDataset;
+  options?: AddDataToMapOptions;
+  config?: ParsedConfig;
+  info?: Partial<MapInfo>;
+};
+
+export type ActionHandler<A extends (...args: any) => any> = (...args: Parameters<A>) => void;
+
+/**
+ * Add data to kepler.gl reducer, prepare map with preset configuration if config is passed.
+ * Kepler.gl provides a handy set of utils to parse data from different formats to the `data` object required in dataset. You rarely need to manually format the data obejct.
+ *
+ * Use `KeplerGlSchema.getConfigToSave` to generate a json blob of the currents instance config.
+ * The config object value will always have higher precedence than the options properties.
+ *
+ * Kepler.gl uses `dataId` in the config to match with loaded dataset. If you pass a config object, you need
+ * to match the `info.id` of your dataset to the `dataId` in each `layer`, `filter` and `interactionConfig.tooltips.fieldsToShow`
+ *
+ * @memberof main
+ * @param {Object} data
+ * @param {Array<Object>|Object} data.datasets - ***required** datasets can be a dataset or an array of datasets
+ * Each dataset object needs to have `info` and `data` property.
+ * @param {Object} data.datasets.info -info of a dataset
+ * @param {string} data.datasets.info.id - id of this dataset. If config is defined, `id` should matches the `dataId` in config.
+ * @param {string} data.datasets.info.label - A display name of this dataset
+ * @param {Object} data.datasets.data - ***required** The data object, in a tabular format with 2 properties `fields` and `rows`
+ * @param {Array<Object>} data.datasets.data.fields - ***required** Array of fields,
+ * @param {string} data.datasets.data.fields.name - ***required** Name of the field,
+ * @param {Array<Array>} data.datasets.data.rows - ***required** Array of rows, in a tabular format with `fields` and `rows`
+ *
+ * @param {Object} data.options
+ * @param {boolean} data.options.centerMap `default: true` if `centerMap` is set to `true` kepler.gl will
+ * place the map view within the data points boundaries.  `options.centerMap` will override `config.mapState` if passed in.
+ * @param {boolean} data.options.readOnly `default: false` if `readOnly` is set to `true`
+ * the left setting panel will be hidden
+ * @param {boolean} data.options.keepExistingConfig whether to keep exiting map data and associated layer filter  interaction config `default: false`.
+ * @param {Object} data.config this object will contain the full kepler.gl instance configuration {mapState, mapStyle, visState}
+ * @public
+ * @example
+ *
+ * // app.js
+ * import {addDataToMap} from 'kepler.gl/actions';
+ *
+ * const sampleTripData = {
+ *  fields: [
+ *    {name: 'tpep_pickup_datetime', format: 'YYYY-M-D H:m:s', type: 'timestamp'},
+ *    {name: 'pickup_longitude', format: '', type: 'real'},
+ *    {name: 'pickup_latitude', format: '', type: 'real'}
+ *  ],
+ *  rows: [
+ *    ['2015-01-15 19:05:39 +00:00', -73.99389648, 40.75011063],
+ *    ['2015-01-15 19:05:39 +00:00', -73.97642517, 40.73981094],
+ *    ['2015-01-15 19:05:40 +00:00', -73.96870422, 40.75424576],
+ *  ]
+ * };
+ *
+ * const sampleConfig = {
+ *   visState: {
+ *     filters: [
+ *       {
+ *         id: 'me',
+ *         dataId: 'test_trip_data',
+ *         name: 'tpep_pickup_datetime',
+ *         type: 'timeRange',
+ *         enlarged: true
+ *       }
+ *     ]
+ *   }
+ * }
+ *
+ * this.props.dispatch(
+ *   addDataToMap({
+ *     datasets: {
+ *       info: {
+ *         label: 'Sample Taxi Trips in New York City',
+ *         id: 'test_trip_data'
+ *       },
+ *       data: sampleTripData
+ *     },
+ *     options: {
+ *       centerMap: true,
+ *       readOnly: false,
+ *       keepExistingConfig: false
+ *     },
+ *     info: {
+ *       title: 'Taro and Blue',
+ *       description: 'This is my map'
+ *     },
+ *     config: sampleConfig
+ *   })
+ * );
+ */
+export const addDataToMap: (
+  data: AddDataToMapPayload
+) => {
+  type: typeof ActionTypes.ADD_DATA_TO_MAP;
+  payload: AddDataToMapPayload;
+} = createAction(ActionTypes.ADD_DATA_TO_MAP, (data: AddDataToMapPayload) => ({payload: data}));
+
+/**
+ * Reset all sub-reducers to its initial state. This can be used to clear out all configuration in the reducer.
+ * @memberof main
+ * @public
+ */
+export const resetMapConfig: () => {type: typeof ActionTypes.RESET_MAP_CONFIG} = createAction(
+  ActionTypes.RESET_MAP_CONFIG
+);
+
+export type ReceiveMapConfigPayload = {
+  config: ParsedConfig;
+  options?: AddDataToMapOptions;
+  bounds?: Bounds;
+};
+/**
+ * Pass config to kepler.gl instance, prepare the state with preset configs.
+ * Calling `KeplerGlSchema.parseSavedConfig` to convert saved config before passing it in is required.
+ *
+ * You can call `receiveMapConfig` before passing in any data. The reducer will store layer and filter config, waiting for
+ * data to come in. When data arrives, you can call `addDataToMap` without passing any config, and the reducer will try to match
+ * preloaded configs. This behavior is designed to allow asynchronous data loading.
+ *
+ * It is also useful when you want to prepare the kepler.gl instance with some preset layer and filter settings.
+ * **Note** Sequence is important, `receiveMapConfig` needs to be called __before__ data is loaded. Currently kepler.gl doesn't allow calling `receiveMapConfig` after data is loaded.
+ * It will reset current configuration first then apply config to it.
+ * @memberof main
+ * @param {Object} config - ***required** The Config Object
+ * @param {Object} options - ***optional** The Option object
+ * @param {boolean} options.centerMap `default: true` if `centerMap` is set to `true` kepler.gl will
+ * place the map view within the data points boundaries
+ * @param {boolean} options.readOnly `default: false` if `readOnly` is set to `true`
+ * the left setting panel will be hidden
+ * @param {boolean} options.keepExistingConfig whether to keep exiting layer filter and interaction config `default: false`.
+ * @param {boolean} options.autoCreateLayers whether to automatically create layers based on dataset columns `default: true`.
+ * @public
+ * @example
+ * import {receiveMapConfig} from 'kepler.gl/actions';
+ * import KeplerGlSchema from 'kepler.gl/schemas';
+ *
+ * const parsedConfig = KeplerGlSchema.parseSavedConfig(config);
+ * this.props.dispatch(receiveMapConfig(parsedConfig));
+ */
+export const receiveMapConfig: (
+  config: ReceiveMapConfigPayload['config'],
+  options: ReceiveMapConfigPayload['options']
+) => {
+  type: typeof ActionTypes.RECEIVE_MAP_CONFIG;
+  payload: ReceiveMapConfigPayload;
+} = createAction(
+  ActionTypes.RECEIVE_MAP_CONFIG,
+  (config: ReceiveMapConfigPayload['config'], options: ReceiveMapConfigPayload['options']) => ({
+    payload: {
+      config,
+      options
+    }
+  })
+);
+
+export type KeplerGlInitPayload = {
+  mapboxApiAccessToken?: string;
+  mapboxApiUrl?: string;
+  mapStylesReplaceDefault?: boolean;
+  initialUiState?: Partial<UiState>;
+};
+/**
+ * Initialize kepler.gl reducer. It is used to pass in `mapboxApiAccessToken` to `mapStyle` reducer.
+ * @memberof main
+ * @param {object} payload
+ * @param payload.mapboxApiAccessToken - mapboxApiAccessToken to be saved to mapStyle reducer
+ * @param payload.mapboxApiUrl - mapboxApiUrl to be saved to mapStyle reducer.
+ * @param payload.mapStylesReplaceDefault - mapStylesReplaceDefault to be saved to mapStyle reducer
+ * @param payload.initialUiState - initial ui state
+ * @public
+ */
+export const keplerGlInit: (
+  options?: KeplerGlInitPayload
+) => {
+  type: typeof ActionTypes.INIT;
+  payload: KeplerGlInitPayload;
+} = createAction(ActionTypes.INIT, (payload: KeplerGlInitPayload) => ({payload}));
+
+/**
+ * This declaration is needed to group actions in docs
+ */
+/**
+ * Main kepler.gl actions, these actions handles loading data and config into kepler.gl reducer. These actions
+ * is listened by all subreducers,
+ * @public
+ */
+/* eslint-disable no-unused-vars */
+// @ts-ignore
+const main = null;
+/* eslint-enable no-unused-vars */

package/src/actions/identity-actions.ts

@@ -0,0 +1,116 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import {createAction} from '@reduxjs/toolkit';
+import ActionTypes from 'constants/action-types';
+import {UiState} from 'reducers/ui-state-updaters';
+
+export type RegisterEntryUpdaterAction = {
+  payload: {
+    id: string;
+    mint?: boolean;
+    mapboxApiAccessToken?: string;
+    mapboxApiUrl?: string;
+    mapStylesReplaceDefault?: boolean;
+    initialUiState?: Partial<UiState>;
+  };
+};
+/**
+ *
+ * Add a new kepler.gl instance in `keplerGlReducer`. This action is called under-the-hood when a `KeplerGl` component is **mounted** to the dom.
+ * Note that if you dispatch actions such as adding data to a kepler.gl instance before the React component is mounted, the action will not be
+ * performed. Instance reducer can only handle actions when it is instantiated.
+ * @memberof rootActions
+ * @param payload
+ * @param payload.id - ***required** The id of the instance
+ * @param payload.mint - Whether to use a fresh empty state, when `mint: true` it will *always* load a fresh state when the component is re-mounted.
+ * When `mint: false` it will register with existing instance state under the same `id`, when the component is unmounted then mounted again. Default: `true`
+ * @param payload.mapboxApiAccessToken - mapboxApiAccessToken to be saved in `map-style` reducer.
+ * @param payload.mapboxApiUrl - mapboxApiUrl to be saved in `map-style` reducer.
+ * @param payload.mapStylesReplaceDefault - mapStylesReplaceDefault to be saved in `map-style` reducer.
+ * @param payload.initialUiState - initial ui state
+ * @public
+ */
+export const registerEntry: (
+  entry: RegisterEntryUpdaterAction['payload']
+) => {
+  type: typeof ActionTypes.REGISTER_ENTRY;
+  payload: RegisterEntryUpdaterAction['payload'];
+} = createAction(ActionTypes.REGISTER_ENTRY, (payload: RegisterEntryUpdaterAction['payload']) => ({
+  payload
+}));
+
+/**
+ *
+ * Delete an instance from `keplerGlReducer`. This action is called under-the-hood when a `KeplerGl` component is **un-mounted** to the dom.
+ * If `mint` is set to be `true` in the component prop, the instance state will be deleted from the root reducer. Otherwise, the root reducer will keep
+ * the instance state and later transfer it to a newly mounted component with the same `id`
+ * @memberof rootActions
+ * @param {string} id - the id of the instance to be deleted
+ * @public
+ */
+export const deleteEntry: (
+  id: string
+) => {
+  type: typeof ActionTypes.DELETE_ENTRY;
+  payload: string;
+} = createAction(ActionTypes.DELETE_ENTRY, (id: string) => ({payload: id}));
+
+/**
+ *
+ * Rename an instance in the root reducer, keep its entire state
+ *
+ * @memberof rootActions
+ * @param {string} oldId - ***required** old id
+ * @param {string} newId - ***required** new id
+ * @public
+ */
+export const renameEntry: (
+  oldId: string,
+  newId: string
+) => {
+  type: typeof ActionTypes.RENAME_ENTRY;
+  payload: {
+    oldId: string;
+    newId: string;
+  };
+} = createAction(ActionTypes.RENAME_ENTRY, (oldId: string, newId: string) => ({
+  payload: {
+    oldId,
+    newId
+  }
+}));
+
+/**
+ * This declaration is needed to group actions in docs
+ */
+/**
+ * Root actions managers adding and removing instances in root reducer.
+ * Under-the-hood, when a `KeplerGl` component is mounted or unmounted,
+ * it will automatically calls these actions to add itself to the root reducer.
+ * However, sometimes the data is ready before the component is registered in the reducer,
+ * in this case, you can manually call these actions or the corresponding updater to add it to the reducer.
+ *
+ * @public
+ */
+/* eslint-disable no-unused-vars */
+// @ts-ignore
+const rootActions = null;
+/* eslint-enable no-unused-vars */

package/src/actions/map-state-actions.ts

@@ -0,0 +1,116 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import {createAction} from '@reduxjs/toolkit';
+import ActionTypes from 'constants/action-types';
+import {Merge} from '../reducers/types';
+import {Bounds, Viewport} from '../reducers/map-state-updaters';
+
+export type TogglePerspectiveUpdaterAction = {};
+/**
+ *
+ * Toggle between 3d and 2d map.
+ * @memberof mapStateActions
+ * @public
+ * @example
+ * import {togglePerspective} from 'kepler.gl/actions';
+ * this.props.dispatch(togglePerspective());
+ */
+export const togglePerspective: () => Merge<
+  TogglePerspectiveUpdaterAction,
+  {type: typeof ActionTypes.TOGGLE_PERSPECTIVE}
+> = createAction(ActionTypes.TOGGLE_PERSPECTIVE);
+
+export type FitBoundsUpdaterAction = {payload: Bounds};
+/**
+ * Fit map viewport to bounds
+ * @memberof mapStateActions
+ * @param {Array<Number>} bounds as `[lngMin, latMin, lngMax, latMax]`
+ * @public
+ * @example
+ * import {fitBounds} from 'kepler.gl/actions';
+ * this.props.dispatch(fitBounds([-122.23, 37.127, -122.11, 37.456]));
+ */
+export const fitBounds: (
+  payload: Bounds
+) => Merge<
+  FitBoundsUpdaterAction,
+  {type: typeof ActionTypes.FIT_BOUNDS}
+> = createAction(ActionTypes.FIT_BOUNDS, (bounds: Bounds) => ({payload: bounds}));
+
+export type UpdateMapUpdaterAction = {payload: Viewport};
+/**
+ * Update map viewport
+ * @memberof mapStateActions
+ * @param {Object} viewport viewport object container one or any of these properties `width`, `height`, `latitude` `longitude`, `zoom`, `pitch`, `bearing`, `dragRotate`
+ * @param {Number} [viewport.width] Width of viewport
+ * @param {Number} [viewport.height] Height of viewport
+ * @param {Number} [viewport.zoom] Zoom of viewport
+ * @param {Number} [viewport.pitch] Camera angle in degrees (0 is straight down)
+ * @param {Number} [viewport.bearing] Map rotation in degrees (0 means north is up)
+ * @param {Number} [viewport.latitude] Latitude center of viewport on map in mercator projection
+ * @param {Number} [viewport.longitude] Longitude Center of viewport on map in mercator projection
+ * @param {boolean} [viewport.dragRotate] Whether to enable drag and rotate map into perspective viewport
+ * @public
+ * @example
+ * import {updateMap} from 'kepler.gl/actions';
+ * this.props.dispatch(updateMap({latitude: 37.75043, longitude: -122.34679, width: 800, height: 1200}));
+ */
+
+export const updateMap: (
+  payload: Viewport
+) => Merge<
+  UpdateMapUpdaterAction,
+  {type: typeof ActionTypes.UPDATE_MAP}
+> = createAction(ActionTypes.UPDATE_MAP, (viewport: Viewport) => ({payload: viewport}));
+
+export type ToggleSplitMapUpdaterAction = {
+  payload: number;
+};
+/**
+ * Toggle between single map or split maps
+ * @memberof mapStateActions
+ * @param {Number} [index] index is provided, close split map at index
+ * @public
+ * @example
+ * import {toggleSplitMap} from 'kepler.gl/actions';
+ * this.props.dispatch(toggleSplitMap());
+ */
+export const toggleSplitMap: (
+  payload: number
+) => Merge<
+  ToggleSplitMapUpdaterAction,
+  {type: typeof ActionTypes.TOGGLE_SPLIT_MAP}
+> = createAction(ActionTypes.TOGGLE_SPLIT_MAP, (index: number) => ({payload: index}));
+
+/**
+ * This declaration is needed to group actions in docs
+ */
+/**
+ * Actions handled mostly by  `mapState` reducer.
+ * They manage map viewport update, toggle between 2d and 3d map,
+ * toggle between single and split maps.
+ *
+ * @public
+ */
+/* eslint-disable no-unused-vars */
+// @ts-ignore
+const mapStateActions = null;
+/* eslint-enable no-unused-vars */