Expand JS Tools list

Integrate suggestions, fill out placeholder sections,
& cross-link to discussion issues on Github.

Author: AmeliaBR

index.html

@@ -53,6 +53,15 @@
 a[href]:hover .tag-span, a[href]:focus .tag-span {
   text-decoration: underline;
 }
+/* hack because respec is pulling in too much content */
+.issue > :not(.issue-title) {
+    display: none;
+}
+/* doesn't currently work (repsec drops the second class when processing the issue) */
+.issue.discussion {
+  border-color: hsl(180, 90%, 45%);
+  background: hsl(180, 80%, 90%);
+}
 </style>
 <script class='remove'>
 var respecConfig = {
@@ -275,9 +284,17 @@ <h3>The Maps for HTML Community Group</h3>
 <em>why</em> native HTML web maps would be beneficial,
 and <em>how</em> they should best be defined.
 </p>
-<p class="ednote">
+<div class="ednote">
+<p>
 This report is a work in progress!
 Feedback and contributions are welcome.
+Most sections of the report include links to a discussion issue on GitHub.
+Use those issues to suggest corrections, additions,
+or changes to the conclusions.
+To suggest a new section (e.g., a new use case),
+please start a new issue.
+</p>
+<p>
 To make substantive contributions
 (that is, anything that is bigger than typo corrections or formatting fixes),
 you will need to first
@@ -948,10 +965,7 @@ <h2>Reviewed JavaScript Tools</h2>
 In addition, multiple open source JavaScript libraries
 have developed to make it easier for website authors to build on other map data services.
 </p>
-<p class="issue">
-Need data on the frequency of use of the different JS tools.
-<a href="https://trends.builtwith.com/mapping/"></a> has numbers, but no methodology.
-</p>
+<p class="issue" data-number="25"></p>
 <p>
 The reviewed implementations come in three forms:
 </p>
@@ -967,7 +981,7 @@ <h2>Reviewed JavaScript Tools</h2>
 <li>
 HTML custom elements,
 with configuration through attributes and child elements.
-<p class="issue">Need to identify reasonably popular web maps tools based on custom elements.</p>
+<p class="issue" data-number="23"></p>
 </li>
 </ul>
 <p>
@@ -1017,7 +1031,7 @@ <h2>Reviewed JavaScript Tools</h2>
 we don't strictly exclude paid features from our assessment of support.
 </p>
 
-<section>
+<section id="google-maps">
 <h3>Google Maps embeds and Google Maps Platform API</h3>
 <p>
 By far the most frequently used map widget on the web,<sup>[citation needed]</sup>
@@ -1033,52 +1047,112 @@ <h3>Google Maps embeds and Google Maps Platform API</h3>
 The Google Maps Platform includes a JavaScript API
 for generating map viewers and adding custom features and data layers.
 It also includes methods to access more complex search functions, local images, and other data.
-Most features require an API key and usage is billed per page view.
+Most features require an API key and is billed by usage (page views or API requests).
 </p>
+<p class="issue discussion" data-number="9"></p>
 </section>
 
-<section>
+<section id="openstreetmap">
 <h3>OpenStreetMap embeds</h3>
 <p>
-
+<a href="https://openstreetmap.org/">OpenStreetMap</a> is a project to compile free-to-use wayfinding maps of the entire Earth,
+from crowdsourced contributions.
+</p>
+<p>
+The interactive map on the group's website can be used to generate embeddable map widgets.
+Various options can also be specified
+<a href="https://wiki.openstreetmap.org/wiki/Browsing#Other_URL_tricks">in the URL</a> for the embed source.
 </p>
+<p>
+The image tiles created by the project can also be accessed directly by URL recipes,
+and these are used in other map viewer widgets and APIs.
+The raw data is also re-processed and used by other map data services.
+</p>
+<p class="issue discussion" data-number="26"></p>
 </section>
 
-<section>
-<h3>Bing Maps embeds</h3>
+<section id="bing-maps">
+<h3>Bing Maps embeds and Bing Maps Control API</h3>
 <p>
-
+<a href="https://www.bing.com/maps#">Bing maps</a> provides embeds that can be generated from their website.
+For more complex options, the <a href="https://www.microsoft.com/en-us/maps/v8-control">API</a>
+can be used to generate widgets with minimal configuration,
+but also provides client-side APIs for manipulating the map,
+as well as an interface to Bing's search services.
+API tokens are required; free and paid plans are available, with usage caps.
 </p>
+<p class="issue discussion" data-number="27"></p>
 </section>
 
-<section>
+<section id="mapkit-js">
 <h3>MapKit JS (Apple Maps) API</h3>
 <p>
+<a href="https://developer.apple.com/maps/mapkitjs/">MapKit JS</a> provides
+a JS framework for integrating Apple Maps in a website,
+with a client-side API for customizing interactions,
+and integrations with Apple search services.
+</p>
+<p>
+A developer account is required,
+along with a method of generating encrypted API tokens on demand on the webserver.
+</p>
+<p class="issue discussion" data-number="28"></p>
+</section>
 
+<section id="mapbox">
+<h3>Mapbox GL JS API</h3>
+<p>
+<a href="https://docs.mapbox.com/">Mapbox</a> provides
+map data as a service, as well as frameworks for multiple platforms.
+The GL JS framework generates map viewer widgets from client-side JavaScript calls,
+using WebGL for the actual rendering.
+Alternatively, the Mapbox <a href="https://docs.mapbox.com/api/maps/#maps">Maps API</a>
+returns complete HTML slippy maps based on URL configuration,
+and so can be used as an iframe source.
+</p>
+<p>
+An API key is required, with cost based on usage.
 </p>
+<p class="issue discussion" data-number="12"></p>
 </section>
 
-<section>
+<section id="leaflet-js">
 <h3>Leaflet.js API</h3>
 <p>
-Leaflet is a popular JavaScript framework for building customized map views.
+<a href="https://leafletjs.com/">Leaflet</a> is a popular open-source JavaScript framework
+for building customized map views.
 It doesn't currently have a declarative API,
 but widgets similar to map embeds can be generated with a few calls to the library methods.
 </p>
 <p>
 Leaflet isn't associated with any particular map data source.
 It can use image tiles from most web map (tile) services.
 </p>
-<p>
-This review is based on the <a href="https://leafletjs.com/reference-1.4.0.html">version 1.4.0 API docs</a>.
-</p>
+<p class="issue discussion" data-number="29"></p>
 </section>
 
-<section>
+<section id="openlayers">
 <h3>OpenLayers API</h3>
 <p>
+OpenLayers is one of the most established open-source libraries
+for creating dynamic web maps from map data in standard formats.
+As with Leaflet, it isn't associated with any particular map service.
+A basic slippy map can be created with a few lines of custom JavaScript.
+</p>
+<p class="issue discussion" data-number="30"></p>
+</section>
 
+<section id="d3-geo">
+<h3>D3 Geographies APIs</h3>
+<p>
+The data visualization library D3 includes the <a href="https://github.com/d3/d3-geo">d3-geo module</a>
+which defines methods for manipulating vector map data
+(which the website author must provide).
+Unlike the other JS tools being reviewed here,
+D3 does not include code for a ready-made map viewer widget,
+but it is used for custom client-side mapping applications.
 </p>
+<p class="issue discussion" data-number="13"></p>
 </section>
 </section>
 
@@ -1874,6 +1948,7 @@ <h4><!-- Goal that user/author is trying to achieve --></h4>
 See <a href="examples/#(add a new file for each use case)" target="examples">examples of <!-- description --></a>
 as implemented by the reference JavaScript tools.
 </p>
+<p class="issue discussion" data-number="(GH issue number for discussion)"></p>
 
 <h5>Required capabilities</h5>
 <ul data-ucr-role="required-capabilities">
@@ -1889,6 +1964,7 @@ <h4><!-- Action that is/should be possible --></h4>
 <p>
 <!-- Description of how it should work & why it is useful to users/authors of maps. -->
 </p>
+<p class="issue discussion" data-number="(GH issue number for discussion)"></p>
 
 <h5>Existing implementations</h5>
 <p>