keplergl
diff --git a/‎README.md‎
Lines changed: 3 additions & 2 deletions b/‎README.md‎
Lines changed: 3 additions & 2 deletions
diff --git a/‎SUMMARY.md‎
Lines changed: 2 additions & 1 deletion b/‎SUMMARY.md‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎contributing/DEVELOPERS.md‎
Lines changed: 25 additions & 0 deletions b/‎contributing/DEVELOPERS.md‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎docs/RFC/table-class.md‎
Lines changed: 3 additions & 3 deletions b/‎docs/RFC/table-class.md‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎docs/api-reference/actions/actions.md‎
Lines changed: 16 additions & 18 deletions b/‎docs/api-reference/actions/actions.md‎
Lines changed: 16 additions & 18 deletions
diff --git a/‎docs/api-reference/advanced-usages/custom-initial-state.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/api-reference/advanced-usages/custom-initial-state.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/api-reference/advanced-usages/custom-map-styles.md‎
Lines changed: 2 additions & 2 deletions b/‎docs/api-reference/advanced-usages/custom-map-styles.md‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎docs/api-reference/advanced-usages/custom-mapbox-host.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/api-reference/advanced-usages/custom-mapbox-host.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/api-reference/advanced-usages/forward-actions.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/api-reference/advanced-usages/forward-actions.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/api-reference/advanced-usages/saving-loading-w-schema.md‎
Lines changed: 2 additions & 2 deletions b/‎docs/api-reference/advanced-usages/saving-loading-w-schema.md‎
Lines changed: 2 additions & 2 deletions
@@ -51,8 +51,9 @@ Kepler.gl is also a React component that uses [Redux](https://redux.js.org/) to
 
 ## Env
 
-Use Node 18.18.2 or above, older node versions have not been supported/ tested.
-For best results, use [nvm](https://github.com/creationix/nvm) `nvm install`.
+For **developing this repository**, use Node **18.18.2** (see `.nvmrc`): run `nvm install` and `nvm use`. Newer Node versions can make `yarn install` / `yarn bootstrap` try to compile the `gl` dev dependency from source; if that fails, see [Troubleshooting: gl package install](contributing/DEVELOPERS.md#troubleshooting-gl-package-install).
+
+When **using kepler.gl as a dependency** in your own app, use Node 18.18.2 or a supported LTS; older Node versions are not supported or tested.
 
 ## Install kepler.gl modules
 
 
@@ -70,7 +70,7 @@
 * [Examples](examples/README.md)
   * [Node/Express](examples/node-app/README.md)
   * [Demo App](examples/demo-app/README.md)
-  * [Open modal](examples/replace-component/README.md)
+  * [Replace Component](examples/replace-component/README.md)
   * [Open modal](examples/open-modal/README.md)
   * [UMD client](examples/umd-client/README.md)
   * [Customize kepler.gl Theme](examples/custom-theme/README.md)
@@ -80,3 +80,4 @@
   * [Contributor Covenant Code of Conduct](contributing/CODE_OF_CONDUCT.md)
 * [Change Log](CHANGELOG.md)
 * [Upgrade Guide](UPGRADE-GUIDE.md)
+* [Upgrade Guide v3.3](docs/upgrade-guide-v3.3.md)
@@ -3,6 +3,7 @@
 ## Table of contents
 
 - [Development Setup](./#development-setup)
+- [Troubleshooting: gl package install](./#troubleshooting-gl-package-install)
 - [Running Tests](./#running-tests)
 - [Coding Rules](./#coding-rules)
 - [Commit Message Guidelines](./#git-commit-guidelines)
@@ -68,6 +69,7 @@ On Unix, MacOS
 # install Volta on Unix
 curl https://get.volta.sh | bash
 ```
+
 On Windows
 
 ```bash
@@ -117,6 +119,29 @@ An demo app will be served at `http://localhost:8080/`
 
 This is the demo app we hosted on [http://kepler.gl/#/demo][demo-app]. By default, it serves non-minified source code inside the src directory.
 
+### Troubleshooting: gl package install
+
+Yarn may report that the `gl` package (a dev dependency used for headless WebGL in tests) **could not be built**. That usually happens for one of two reasons:
+
+1. **No prebuilt binary for your Node version and platform**  
+   `prebuild-install` only ships binaries for certain Node releases and OS/arch pairs (for example, very new Node versions on Apple Silicon often have none). Yarn then falls back to compiling `gl` from source with `node-gyp`.
+
+2. **Source build needs a `python` command**  
+   The ANGLE sources invoked during that compile run `python` (not `python3`). macOS Command Line Tools typically install `python3` only, so the log shows `python: command not found` and `gyp ERR! configure error` even though `node-gyp` found Python 3.
+
+**What to do**
+
+- **Prefer the Node version pinned for this repo** (see `.nvmrc`, currently 18.18.2). After `nvm install` and `nvm use` (or Volta, as above), run `yarn install` / `yarn bootstrap` again. A matching prebuild is often available, so the native compile step never runs.
+
+- **If you must use a newer Node** and the install compiles from source, ensure `python` is on your `PATH` and points to Python 3, for example on macOS:
+
+  ```bash
+  sudo mkdir -p /usr/local/bin
+  sudo ln -sf /usr/bin/python3 /usr/local/bin/python
+  ```
+
+  Use another location if `/usr/local/bin` is not early in your `PATH`.
+
 #### Develop with deck.gl
 
 When develop, upgrade, debug deck.gl, Demo app can load deck.gl directly from src
 
@@ -66,12 +66,12 @@ Missing features
 
 #### Current kepler.gl methods:
 
-1. `initalize`
+1. `initialize`
 
 to replace utils/dataset-utils `createNewDataEntry` This table method takes a `ProtoTable` and returns a `Table` to be saved in kepler state.
 
 ```js
-table.initalize(protoTable);
+table.initialize(protoTable);
 
 // following meta data should be initialized
 table.allIndexes,
@@ -102,7 +102,7 @@ table.allIndexes,
    Value the field value, type the field type
 
 7. `sortDatasetByColumn`
-   Sort a column, return an sorted index, assign to `sortColumn`, `sortOrder`
+   Sort a column, return a sorted index, assign to `sortColumn`, `sortOrder`
 
 8. `filterDataset(filters, layers, opt)`
   to replace `filter-utils.js` `filterDataset`
 
@@ -298,7 +298,7 @@ Callback when load map style success
 
 ### mapConfigChange
 
-Update `visibleLayerGroups`to change layer group visibility
+Update `visibleLayerGroups` to change layer group visibility
 
 - **ActionTypes**: [`ActionTypes.MAP_CONFIG_CHANGE`][12]
 - **Updaters**: [`mapStyleUpdaters.mapConfigChangeUpdater`][171]
@@ -343,12 +343,12 @@ Set 3d building layer group color
 ## main
 
 Main kepler.gl actions, these actions handles loading data and config into kepler.gl reducer. These actions
-is listened by all subreducers,
+are listened to by all subreducers.
 
 ### addDataToMap
 
 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.
+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 object.
 
 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.
@@ -533,7 +533,7 @@ Trigger CPU filter of selected dataset
 
 **Parameters**
 
-- `dataId` **([string][162] | Arrary&lt;[string][162]>)** single dataId or an array of dataIds
+- `dataId` **([string][162] | Array&lt;[string][162]>)** single dataId or an array of dataIds
 
 Returns **{type: ActionTypes.APPLY_CPU_FILTER, dataId: [string][162]}**
 
@@ -593,7 +593,7 @@ Update layer text label
 
 ### layerTypeChange
 
-Update layer type. Previews layer config will be copied if applicable.
+Update layer type. Previous layer config will be copied if applicable.
 
 - **ActionTypes**: [`ActionTypes.LAYER_TYPE_CHANGE`][12]
 - **Updaters**: [`visStateUpdaters.layerTypeChangeUpdater`][192]
@@ -697,7 +697,7 @@ Returns **{type: ActionTypes.MAP_CLICK}**
 
 ### onMouseMove
 
-Trigger map mouse moveevent, payload would be
+Trigger map mouse move event, payload would be
 React-map-gl MapLayerMouseEvent
 [https://visgl.github.io/react-map-gl/docs/api-reference/types#maplayermouseevent][202]
 
@@ -708,7 +708,7 @@ React-map-gl MapLayerMouseEvent
 
 - `evt` **[Object][164]** MapLayerMouseEvent
 
-Returns **{type: ActionTypes.MAP_CLICK}**
+Returns **{type: ActionTypes.MOUSE_MOVE}**
 
 ### removeDataset
 
@@ -784,10 +784,10 @@ Set the map mode
 **Examples**
 
 ```javascript
-import {setMapMode} from '@kepler.gl/actions';
+import {setEditorMode} from '@kepler.gl/actions';
 import {EDITOR_MODES} from '@kepler.gl/constants';
 
-this.props.dispatch(setMapMode(EDITOR_MODES.DRAW_POLYGON));
+this.props.dispatch(setEditorMode(EDITOR_MODES.DRAW_POLYGON));
 ```
 
 ### setFilter
@@ -822,18 +822,16 @@ Returns **{type: ActionTypes.SET_FILTER_PLOT, idx: any, newProp: any}**
 
 ### setMapInfo
 
-Set the property of a filter plot
+Set map info such as title and description
 
 - **ActionTypes**: [`ActionTypes.SET_MAP_INFO`][12]
 - **Updaters**: [`visStateUpdaters.setMapInfoUpdater`][211]
 
 **Parameters**
 
-- `info`
-- `idx` **[Number][188]**
-- `newProp` **[Object][164]** key value mapping of new prop `{yAxis: 'histogram'}`
+- `info` **[Object][164]** map info object, e.g. `{title: 'My Map', description: 'My map description'}`
 
-Returns **{type: ActionTypes.SET_FILTER_PLOT, idx: any, newProp: any}**
+Returns **{type: ActionTypes.SET_MAP_INFO, info: info}**
 
 ### showDatasetTable
 
@@ -958,9 +956,9 @@ Returns **{type: ActionTypes.UPDATE_VIS_DATA, datasets: datasets, options: optio
 ## uiStateActions
 
 Actions handled mostly by `uiState` reducer.
-They manage UI changes in tha app, such as open and close side panel,
+They manage UI changes in the app, such as open and close side panel,
 switch between tabs in the side panel, open and close modal dialog for exporting data / images etc.
-It also manges which settings are selected during image and map export
+It also manages which settings are selected during image and map export
 
 ### addNotification
 
@@ -1037,7 +1035,7 @@ Whether to export filtered data, `true` or `false`
 
 **Parameters**
 
-- `payload` **[boolean][165]** set `true` to ony export filtered data
+- `payload` **[boolean][165]** set `true` to only export filtered data
 
 ### setExportImageDataUri
 
@@ -1474,7 +1472,7 @@ Set the export map format (html, json)
 [173]: ../reducers/map-style.md#mapstyleupdatersrequestmapstylesupdater
 [174]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 [175]: ../reducers/map-style.md#mapstyleupdatersset3dbuildingcolorupdater
-[176]: ../reducers/composers.md#combinedupdatersadddatatomapupdater
+[176]: ../reducers/combine.md#combinedupdatersadddatatomapupdater
 [177]: ../reducers/map-style.md#mapstyleupdatersinitmapstyleupdater
 [178]: ../reducers/map-state.md#mapstateupdatersreceivemapconfigupdater
 [179]: ../reducers/map-style.md#mapstyleupdatersreceivemapconfigupdater
 
@@ -6,7 +6,7 @@ Here is an example modify `uiState` `initialState` to hide side panel, and selec
 
 ```js
 import {combineReducers} from 'redux';
-import {keplerGlReducer} from '@kepler.gl/reducers';
+import keplerGlReducer from '@kepler.gl/reducers';
 
 const customizedKeplerGlReducer = keplerGlReducer
   .initialState({
 
@@ -7,7 +7,7 @@ By default, kepler.gl uses mapbox-gl.js to render its base maps, displayed in [m
 You can custom kepler.gl to use other base map services, by passing in style.json written in [Mapbox GL Style Spec](https://docs.mapbox.com/mapbox-gl-js/style-spec/). With custom style.json kepler.gl can render base map independent of mapbox vector tile service.
 
 
-For instance. there is a example [style.json](https://raw.githubusercontent.com/heshan0131/kepler.gl-data/master/style/basic.json).  It points to the tile server described in the `sources` field.
+For instance. there is an example [style.json](https://raw.githubusercontent.com/heshan0131/kepler.gl-data/master/style/basic.json).  It points to the tile server described in the `sources` field.
 
 ```json
   "sources": {
@@ -129,7 +129,7 @@ If your map styles are not using Mapbox services, and you replaced all kepler.gl
 
 #### 4. `DEFAULT_LAYER_GROUPS`
 
-If `layerGroups` is not suppied, kepler.gl uses the default layer groups below. 
+If `layerGroups` is not supplied, kepler.gl uses the default layer groups below. 
 
 
 ```js
 
@@ -38,7 +38,7 @@ and In render:
   <KeplerGl
       id="foo"
       mapboxApiAccessToken={this.token}
-      mapboxApiUrl={}
+      mapboxApiUrl={this.apiHost}
       mapStyles={this.mapStyles}
       width={width}
       height={height}/>
 
@@ -53,7 +53,7 @@ import {toggleFullScreen, wrapTo} from '@kepler.gl/actions';
 const wrapToMap = wrapTo('foo');
 const MapContainer = ({dispatch}) => (
   <div>
-    <button onClick={() => dispatch(wrapToMap(toggleFullScreen())} />
+    <button onClick={() => dispatch(wrapToMap(toggleFullScreen()))} />
     <KeplerGl id="foo"/>
   </div>
 );
 
@@ -2,7 +2,7 @@
 
 ![Processor and Schema][processor-schema]
 
-Kelper.gl provides a schema manager to save and load maps. It converts current map data and configuration into a smaller JSON blob. You can then load that JSON blob into an empty map by passing it to `addDataToMap`.
+Kepler.gl provides a schema manager to save and load maps. It converts current map data and configuration into a smaller JSON blob. You can then load that JSON blob into an empty map by passing it to `addDataToMap`.
 
 The reason kepler.gl provides a Schema manager is to make it easy for users to connect the kepler.gl client app to any database, saving map data / config and later load it back. With the schema manager, a map saved in an older version can still be parsed and loaded with the latest kepler.gl library.
 
@@ -16,7 +16,7 @@ Under the hood, `SchemaManager.save()` calls `SchemaManager.getDatasetToSave()`
 - `SchemaManager.getDatasetToSave()` will output an array of dataset.
 - `SchemaManager.getConfigToSave()` will output a JSON blob of the current config.
 
-In the example blow, `foo` is the id of the KeplerGl instance to be save.
+In the example below, `foo` is the id of the KeplerGl instance to be save.
 
 ```js
 import KeplerGlSchema from '@kepler.gl/schemas';