[docs] use appropriate-images for examples to increase page speed (#7…

…900)

* use appropriate-images for examples

* move @mapbox/appropriate-images to optionalDependencies

* class -> className

* rm docs/img/dist

* ignore docs/img/dist

* create `build-images` script to run appropriate-images on `build-docs` and `start-docs`; move appropriate-images as devDep

* add note to documentation to suggust using `nvm use 8` if contributor receives error

* remove test to check for generated image in dist/

* automate image.config.js and update documentation

* add eslint-disable-line as image.config.json is generated on build

.gitignore

@@ -4,6 +4,7 @@
 /docs/pages/dist/mapbox-gl-dev.js
 /docs/pages/dist/mapbox-gl.js
 /docs/pages/dist/mapbox-gl-unminified.js
+/docs/img/dist/
 *.js.map
 node_modules
 package-lock.json

docs/README.md

@@ -33,10 +33,14 @@ In the `.html` file, write the HTML and JavaScript constituting the example.
 * Do **not** use custom styles from your personal account. Use only the default `mapbox` account styles.
 * When embedding literal JSON (GeoJSON or Mapbox style snippets) into script code, double-quote property names and string values. Elsewhere, use single-quoted strings.
 
-Every example must have an accompanying thumbnail image:
+Every example **must** have an accompanying image:
 
-* Save a thumbnail image (1200 x 500 pixel .png, under 500 KB) in `docs/pages/img/`.
-* The file name of the image must match the example's file name.
+1. Save the image in `docs/img/src/`. Image requirements:
+  - The file name of the image **must** match the example's file name
+  - 1200 x 500 pixel
+  - png format
+2. Run `npm run build-images` to generate the appropriate images. Alternatively, when you run `npm run start-docs` the site will generate the images.
+3. Run the site locally to verify that your example image is loading as expected.
 
 ## Running the Documentation Server Locally
 
@@ -47,6 +51,8 @@ npm run start-docs
 
 The command will print the URL you can use to view the documentation.
 
+💡 If you receive an error related to `@mapbox/appropriate-images`, try `nvm use 8 && npm run start-docs`.
+
 ## Committing and Publishing Documentation
 
 The mapbox-gl-js repository has both `master` and `publisher-production` as active branches. The **`master` branch** is used for mainline code development: the next version of mapbox-gl-js will come from the code in this branch, and it may contain documentation and examples for APIs that are not yet part of a public release. The **`publisher-production` branch** is published to https://www.mapbox.com/mapbox-gl-js/ on any push to the branch. For the purposes of documentation changes, use these two branches as follows:

docs/bin/appropriate-images.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path'); // eslint-disable-line import/no-commonjs
+const appropriateImages = require('@mapbox/appropriate-images'); // eslint-disable-line import/no-commonjs
+const imageConfig = require('../img/dist/image.config.json'); // eslint-disable-line import/no-commonjs
+
+appropriateImages.createCli(imageConfig, {
+    inputDirectory: path.join(__dirname, '../img/src'),
+    outputDirectory: path.join(__dirname, '../img/dist')
+});

docs/bin/build-image-config.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// builds image.config.json
+// this configuration file is required to generate the appropriate images sizes with docs/bin/appropriate-images.js
+// it is also required in react component that loads the image in components/appropriate-image.js
+const imagePath = './docs/img/src/';
+
+const imageConfig = require('fs').readdirSync(imagePath).reduce((obj, image) => {
+    const ext = require('path').extname(`${imagePath}${image}`);
+    // only process png
+    if (ext === '.png') {
+        const key = image.replace(ext, '');
+        // set sizes for all images
+        const sizes = [{ width: 800 }, { width: 500 }];
+        // set additional sizes for specific images
+        if (key === 'simple-map') sizes.push({ width: 1200 });
+        obj[key] = {
+            basename: image,
+            sizes
+        };
+    }
+    return obj;
+}, {});
+
+require('fs').writeFileSync('./docs/img/dist/image.config.json', JSON.stringify(imageConfig));

docs/components/appropriate-image.js

@@ -0,0 +1,12 @@
+import { scopeAppropriateImage } from '@mapbox/appropriate-images-react';
+import imageConfig from '../img/dist/image.config.json'; // eslint-disable-line import/no-unresolved
+// image.config.json is generated on build
+
+// See https://github.com/mapbox/appropriate-images-react#appropriateimage
+// The required prop is `imageId`, which must correspond to a key in the
+// imageConfig.
+const AppropriateImage = scopeAppropriateImage(imageConfig, {
+    transformUrl: url => require(`../img/dist/${url}`)
+});
+
+export default AppropriateImage;

docs/pages/examples.js

@@ -13,6 +13,8 @@ import Card from '@mapbox/dr-ui/card';
 import PageShell from '../components/page_shell';
 import { tags } from '../data/tags.js';
 import examples from '@mapbox/batfish/data/examples'; // eslint-disable-line import/no-unresolved
+import AppropriateImage from '../components/appropriate-image';
+
 
 const meta = {
     title: 'Mapbox GL JS Examples',
@@ -35,7 +37,11 @@ class ExamplesLandingPage extends React.PureComponent {
                             description=''
                             path={example.path}
                             thumbnail={
-                                <div className="h120 w-full" style={{ backgroundImage: `url(/mapbox-gl-js/img/${filename}.png)`, backgroundSize: "cover", borderRadius: '4px' }} />
+                                <AppropriateImage
+                                    imageId={filename}
+                                    style={{ borderRadius: '4px' }}
+                                    background={true}
+                                />
                             }
                         />
                     );
@@ -60,7 +66,14 @@ class ExamplesLandingPage extends React.PureComponent {
                     <a className="color-gray-dark color-blue-on-hover transition clip inline-block w-full unprose"
                         href='/mapbox-gl-js/example/simple-map/'
                     >
-                        <div className="relative h240 mb6" style={{ backgroundImage: `url(/mapbox-gl-js/img/simple-map.png)`, backgroundSize: "cover", borderRadius: '4px' }} />
+                        <div className='relative h240 mb6'>
+                            <AppropriateImage
+                                imageId='simple-map'
+                                style={{ borderRadius: '4px' }}
+                                background={true}
+                            />
+
+                        </div>
                         <div className="">
                             <div className="mb3 txt-m">Display a map</div>
                             <div className="color-gray">Initialize a map in an HTML element with Mapbox GL JS.</div>

package.json

@@ -13,6 +13,7 @@
     "node": ">=6.4.0"
   },
   "dependencies": {
+    "@mapbox/appropriate-images-react": "^1.0.0",
     "@mapbox/dr-ui": "0.6.0",
     "@mapbox/geojson-rewind": "^0.4.0",
     "@mapbox/geojson-types": "^1.0.2",
@@ -42,6 +43,7 @@
     "vt-pbf": "^3.1.1"
   },
   "devDependencies": {
+    "@mapbox/appropriate-images": "^2.0.0",
     "@mapbox/batfish": "1.9.8",
     "@mapbox/flow-remove-types": "^1.3.0-await.upstream.2",
     "@mapbox/mapbox-gl-rtl-text": "^0.2.0",
@@ -125,7 +127,8 @@
     "start": "run-p build-token watch-css watch-dev watch-benchmarks watch-style-benchmarks start-server",
     "start-debug": "run-p build-token watch-css watch-dev start-server",
     "start-bench": "run-p build-token watch-benchmarks watch-style-benchmarks start-server",
-    "build-docs": "documentation build --github --format json --config ./docs/documentation.yml --output docs/components/api.json src/index.js",
+    "build-docs": "documentation build --github --format json --config ./docs/documentation.yml --output docs/components/api.json src/index.js && npm run build-images",
+    "build-images": "mkdir -p docs/img/dist && node docs/bin/build-image-config.js && node docs/bin/appropriate-images.js --all",
     "build": "run-s build-docs && batfish build # invoked by publisher when publishing docs on the publisher-production branch",
     "start-docs": "run-s build-prod-min build-css build-docs && DEPLOY_ENV=local batfish start",
     "lint": "eslint --cache --ignore-path .gitignore src test bench docs docs/pages/example/*.html debug/*.html",

test/unit/docs/examples.test.js

@@ -58,11 +58,9 @@ listExamples('./docs/pages/example/').forEach((example) => {
         });
 
         test(`Example image: ${example}`, (t) => {
-            const imagePath = example.replace('./docs/pages/example/', './docs/pages/img/').replace('.js', '.png');
-            t.ok(fs.existsSync(imagePath), `example must have a thumbnail image located at: ${imagePath}`);
-            if (fs.existsSync(imagePath)) {
-                t.ok(fs.statSync(imagePath)["size"] < 500000, 'image must be less than 500 KB');
-            }
+            // check that they saved an image for the example
+            const imagePathSrc = example.replace('./docs/pages/example/', './docs/img/src/').replace('.js', '.png');
+            t.ok(fs.existsSync(imagePathSrc), `example must have an image located at: ${imagePathSrc}`);
             t.end();
         });
     }