update CHANGELOG and Using Classes Synchonously section of README

Author: tomwayson

Diff for: CHANGELOG.md

@@ -5,12 +5,17 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 ### Added
 ### Changed
+- added "Using Modules Synchronously" to the docs (README) - thanks [@stdavis](https://github.com/stdavis)!
 ### Fixed
+- `css: true` uses the correct URL the light theme (`/esri/themes/light/main.css`) - thanks [@stdavis](https://github.com/stdavis)
 ### Removed
 ### Breaking
 
 ## [2.10.1] - 2019-09-27
 
+### Changed
+- Added generics for `loadModules` typings improvements. #183 - thanks [@deskoh](https://github.com/deskoh)!
+
 ## [2.10.0] - 2019-07-03
 ### Added
 - default to JSAPI 4.12; update docs w/ latest version numbers

Diff for: README.md

@@ -29,8 +29,8 @@ See the [Examples](#examples) section below for links to applications that use t
 - [Why is this needed?](#why-is-this-needed)
 - [Examples](#examples)
 - [Advanced Usage](#advanced-usage)
-  - [Using Classes Synchronously](#using-classes-synchronously)
   - [ArcGIS Types](#arcgis-types)
+  - [Using Classes Synchronously](#using-classes-synchronously)
   - [Configuring Dojo](#configuring-dojo)
   - [Overriding ArcGIS Styles](#overriding-arcgis-styles)
   - [Pre-loading the ArcGIS API for JavaScript](#pre-loading-the-arcgis-api-for-javascript)
@@ -289,76 +289,6 @@ See the [examples over at ember-esri-loader](https://github.com/Esri/ember-esri-
 
 ### [FAQS](https://github.com/Esri/esri-loader/issues?utf8=%E2%9C%93&q=label%3AFAQ+sort%3Aupdated-desc)
 
-### Using Classes Synchronously
-
-Let's say you need to create a map in one component, and then in another component create a legend. In this scenario, you need to create the map first, then create the legend only once you have a reference to the map. However, it is unlikely that you have both references to both DOM nodes at the time you want to start creating the map (for example if the legend component is a child of the map component and it's render lifecycle hasn't started yet).
-
-One way to do this would be to add functions like this to a service (or any singleton module in your app):
-
-```javascript
-newMap (elem, options) {
-  // load BOTH the map AND legend modules
-  // even though we're not using the Legend at this time
-  return loadModules(['esri/map', 'esri/dijit/Legend']).then(([Map, Legend]) => {
-    if (!this._Legend) {
-        // keep a reference to the Legend class so that legends can now be created synchronously
-        this._Legend = Legend;
-      }
-      // create and return the map
-      return new Map(elem, options);
-    }
-  );
-}
-// synchronous function to create a new legend
-// will throw an error if newMap() has not already been called and returned
-newLegend (params, srcNodeRef) {
-  if (this._Legend) {
-    return this._Legend(params, srcNodeRef);
-  } else {
-    throw new Error('You must have loaded a map before creating a legend.');
-  }
-}
-```
-
-Once the map component's DOM has loaded (like `ngInit()` or `componentDidMount()`) you can run something like:
-
-```javascript
-mapService.newMap(elemRef, options).then(map => {
-  // TODO: somehow signal to the legend component that the map has loaded
-  // i.e. pass it down as a prop, etc
-});
-```
-
-In the legend component, whenever you receive a new map instance (i.e. via prop, etc), you can run something like:
-
-```javascript
-this.legend = mapService.newLegend({ map: this.map }, elemRef);
-this.legend.startup();
-```
-
-While that is a little complicated, an advantage of this pattern is that you are in complete control over which modules can be made available synchronously, so there's no mystery about why attempts to load modules synchronously might fail (either because the JSAPI hasn't been loaded, or the module is not one of the ones that can be loaded synchronously).
-
-This encourages you to:
-
-1. consolidate your use of ArcGIS API modules in a single or few locations
-1. use only the ArcGIS API modules you need to do ArcGIS API things (map or 3D scene visualizations) and rely on your framework of choice, arcgis-rest-js, and/or modern JavaScript/TypeScript for everything else
-
-The key to success with this kind of pattern is to not overgeneralize, i.e. "adding every module to the modules list and creating a property on the service for each module (for typings and ease of calling)." Instead, focus on the specific workflows of your application. For example, let's say your app has a sidebar component that will need to at some point create a new `SimpleMarkerSymbol`, and you know that component is only visible once the map component has loaded. For this scenario, your service's `createMap()` can lazy-load `SimpleMarkerSymbol` along with whatever other modules it needs to show the map and then set `this._SimpleMarkerSymbol` so that the service's `addSymbolToMap(symbolJson)` will be available the sidebar component:
-
-```javascript
-addSymbolToMap(symbolJson) {
-  if (this._SimpleMarkerSymbol) {
-    const symbol = new this._SimpleMarkerSymbol(symbolJson)
-    // TODO: add the symbol to this._map, etc
-  } else {
-    // this should never happen, but just in case
-    throw new Error('map not loaded yet')
-  }
-}
-```
-
-Sure, it would be a pain to create such a wrapping function for every module, but if you focus on your app's specific workflows, we bet you'll find that you should only need it for a few modules/classes.
-
 ### ArcGIS Types
 
 This library doesn't make any assumptions about which version of the ArcGIS API you are using, so you will have to install the appropriate types. Furthermore, because you don't `import` esri modules directly with esri-loader, you'll have to follow the instructions below to use the types in your application.
@@ -408,6 +338,49 @@ A more complete 3.x sample can be [seen here](https://codesandbox.io/s/rj6jloy4n
 
 For Angular CLI applications, you will also need to add "arcgis-js-api" to `compilerOptions.types` in src/tsconfig.app.json and src/tsconfig.spec.json [as shown here](https://gist.github.com/tomwayson/e6260adfd56c2529313936528b8adacd#adding-the-arcgis-api-for-javascript-types).
 
+### Using Classes Synchronously
+
+Let's say you need to create a map in one component, and then later in another component add a graphic to that map. Unlike creating a map, creating a graphic and adding it to a map is ordinarily a synchronous operation, so it can be inconvenient to have to wait for `loadModules()` just to load the `Graphic` class. One way to handle this is have the function that creates the map _also_ load the `Graphic` class before its needed. You can then hold onto that class for later use to be exposed by a function like  `addGraphicToMap(view, graphicJson)`:
+
+```javascript
+// utils/map.js
+import { loadModules } from 'esri-loader';
+
+// NOTE: module, not global scope
+let _Graphic;
+
+// this will be called by the map component
+export function loadMap(element, mapOptions) {
+  // NOTE: 
+  return loadModules(['esri/Map', 'esri/views/MapView', 'esri/Graphic'], {
+    css: true
+  }).then(([Map, MapView, Graphic]) => {
+    // hold onto the graphic class for later use
+    _Graphic = Graphic;
+    // create the Map
+    const map = new Map(mapOptions);
+    // return a view showing the map at the element
+    return new MapView({
+      map,
+      container: element
+    });
+  });
+}
+
+// this will be called by the component that needs to add the graphic to the map
+export function addGraphicToMap(view, graphicJson) {
+  // make sure that the graphic class has already been loaded
+  if (!_Graphic) {
+    throw new Error('You must load a map before creating new graphics');
+  }
+  view.graphics.add(new _Graphic(graphicJson));
+}
+```
+
+You can [see this pattern in use in a real-world application](https://github.com/tomwayson/create-arcgis-app/blob/master/src/utils/map.js).
+
+See [#124 (comment)](https://github.com/Esri/esri-loader/issues/124#issuecomment-408482410) and [#71 (comment)](https://github.com/Esri/esri-loader/issues/71#issuecomment-381356848) for more background on this pattern.
+
 ### Configuring Dojo
 
 You can pass a [`dojoConfig`](https://dojotoolkit.org/documentation/tutorials/1.10/dojo_config/) option to `loadModules()` or `loadScript()` to configure Dojo before the script tag is loaded. This is useful if you want to use esri-loader to load Dojo packages that are not included in the ArcGIS API for JavaScript such as [FlareClusterLayer](https://github.com/nickcam/FlareClusterLayer).