Feedback from @chughes-lincoln

Author: theduckylittle

docs/howto/configure-measure-tool.rst

@@ -1,9 +1,74 @@
 How-to configure the Measure tool
 =================================
 
-The measure tool is managed as a part of the ServiceManager component.
-Therefore, all the options for the measure tool are passed in as options
-to the ServiceManger component when it's added to the application.
+The measure tool is configured in two places:
+
+#. The application-level ``measure`` configuration object controls which
+   units are offered and whether the on-map annotations start on or off.
+#. The ServiceManager component's ``measureToolOptions`` control the
+   point-coordinate projections and the initially selected units.
+
+Application measure configuration
+---------------------------------
+
+Pass a ``measure`` object when creating the application to control the
+units offered in the tool and the default annotation behavior:
+
+.. code:: javascript
+
+        var app = new gm3.Application({
+            mapserver_url: CONFIG.mapserver_url,
+            mapfile_root: CONFIG.mapfile_root,
+            measure: {
+                lengthUnits: ["m", "km", "ft", "mi", "ch", "r"],
+                areaUnits: ["m", "km", "ft", "mi", "a", "h"],
+                showMeasureLabels: true
+            }
+        });
+
+-  ``lengthUnits`` is the list of length units offered in the tool. Valid
+   values are:
+
+   -  ``m`` for meters.
+   -  ``km`` for kilometers.
+   -  ``ft`` for feet.
+   -  ``mi`` for miles.
+   -  ``ch`` for chains.
+   -  ``r`` for rods.
+
+   The default is ``["m", "km", "ft", "mi", "ch"]``.
+
+-  ``areaUnits`` is the list of area units offered in the tool. Valid
+   values are:
+
+   -  ``m`` for square meters.
+   -  ``km`` for square kilometers.
+   -  ``ft`` for square feet.
+   -  ``mi`` for square miles.
+   -  ``a`` for acres.
+   -  ``h`` for hectares.
+
+   The default is ``["m", "km", "ft", "mi", "a", "h"]``.
+
+-  ``showMeasureLabels`` is a boolean that sets the *initial* state of
+   the on-map measure annotations. ``true`` (the default) shows them,
+   ``false`` hides them until the user turns them on with the labels
+   button. See :doc:`Turning off measure annotations by default
+   <disable-measure-labels>` for details.
+
+.. note::
+
+    Length and area units are paired: selecting a length unit
+    automatically selects a complementary area unit (and vice versa).
+    Chains and rods both pair with acres, following surveyor convention.
+
+ServiceManager options
+----------------------
+
+The measure tool is rendered by the ServiceManager component, so the
+point-coordinate and initial-unit options are passed in as
+``measureToolOptions`` when the ServiceManager is added to the
+application.
 
 Here's the example from the demo:
 
@@ -20,14 +85,10 @@ Here's the example from the demo:
    that is defined the same as with the :doc:`Coordinate
    Display <coordinate-display>`. When a user clicks on a point on
    the map, the point will be shown in all of the defined projections.
--  ``initialUnits`` is one of:
--  ``m`` for meters.
--  ``km`` for kilometers.
--  ``ft`` for feet (this is the default).
--  ``mi`` for miles.
--  ``ch`` for chains.
--  ``a`` for acres.
--  ``h`` for hectares.
+-  ``initialUnits`` overrides the initially selected length and area
+   units when the tool opens. It is a single unit code from the
+   ``lengthUnits``/``areaUnits`` lists above (for example ``m``, ``ft``,
+   or ``ch``).
 
 Example of setting the default units to meters
 ----------------------------------------------

docs/howto/disable-measure-labels.rst

@@ -9,8 +9,9 @@ Users can always toggle the annotations on or off while measuring using
 the labels button in the upper-left map controls.
 
 To change the *default* so the annotations start **off**, set
-``showMeasureLabels`` to ``false`` in the application's ``map``
-configuration object.
+``showMeasureLabels`` to ``false`` in the application's ``measure``
+configuration object, alongside the other measure options such as
+``areaUnits`` and ``lengthUnits``.
 
 Example:
 
@@ -19,7 +20,9 @@ Example:
     var app = new gm3.Application({
         mapserver_url: CONFIG.mapserver_url,
         mapfile_root: CONFIG.mapfile_root,
-        map: {
+        measure: {
+            areaUnits: ["ft", "mi", "a", "h", "m", "km"],
+            lengthUnits: ["ft", "mi", "ch", "r", "m", "km"],
             showMeasureLabels: false
         }
     });

src/gm3/components/map/index.js

@@ -414,10 +414,11 @@ class Map extends React.Component {
     this.configureSelectionLayer();
 
     // Measure annotations are on by default (opt-out).  Honor a deployer's
-    //  config.map.showMeasureLabels override here -- the map mounts once, so
+    //  config.measure.showMeasureLabels override here -- it sits alongside the
+    //  other measure options (areaUnits, lengthUnits).  The map mounts once, so
     //  this seeds the initial state without clobbering later user toggles.
-    if (typeof this.props.config.showMeasureLabels === "boolean") {
-      this.props.setShowMeasureLabels(this.props.config.showMeasureLabels);
+    if (typeof this.props.measureConfig.showMeasureLabels === "boolean") {
+      this.props.setShowMeasureLabels(this.props.measureConfig.showMeasureLabels);
     }
 
     const viewParams = {};
@@ -978,6 +979,7 @@ function mapState(state) {
     mapView: state.map,
     serviceName: state.query.serviceName,
     config: state.config.map || {},
+    measureConfig: state.config.measure || {},
     selectionStyle: state.config.selectionStyle || {},
     // resolve this to meters
     selectionBuffer: util.convertLength(

src/gm3/components/measure/unit.js

@@ -29,8 +29,10 @@ import { useTranslation } from "react-i18next";
 //   - "area":   which area unit to use for a given length unit
 //   - "length": which length unit to use for a given area unit
 const COMPLEMENTARY_UNIT = {
-  // length unit -> area unit
-  area: { m: "m", km: "km", ft: "ft", mi: "mi", ch: "ft" },
+  // length unit -> area unit.  Chains and rods pair with acres: surveyors
+  //  (the chain/rod users) expect acres, and square rods are not a selectable
+  //  area unit, which would otherwise leave the area with no unit chosen.
+  area: { m: "m", km: "km", ft: "ft", mi: "mi", ch: "a", r: "a" },
   // area unit -> length unit
   length: { m: "m", km: "km", ft: "ft", mi: "mi", a: "ft", h: "m" },
 };

src/gm3/reducers/map.js

@@ -55,7 +55,7 @@ const defaultState = {
   editTools: [],
   projection: "EPSG:3857",
   // on-map measure annotations (rendering concerns).  On by default; a
-  //  deployer can opt out via config.map.showMeasureLabels = false.
+  //  deployer can opt out via config.measure.showMeasureLabels = false.
   showMeasureLabels: true,
   measureLengthUnits: "ft",
   measureAreaUnits: "ft",

tests/gm3/components/measure.test.js

@@ -169,7 +169,9 @@ describe("getComplementaryUnit tests", () => {
     expect(getComplementaryUnit("ft", "area")).toBe("ft");
     expect(getComplementaryUnit("m", "area")).toBe("m");
     expect(getComplementaryUnit("km", "area")).toBe("km");
-    expect(getComplementaryUnit("ch", "area")).toBe("ft");
+    // chains and rods pair with acres (surveyor convention).
+    expect(getComplementaryUnit("ch", "area")).toBe("a");
+    expect(getComplementaryUnit("r", "area")).toBe("a");
   });
 
   test("maps an area unit to its preferred length unit", () => {