maplibre-gl 3.1.0 → 3.2.0-pre.2

package/README.md

@@ -4,7 +4,7 @@
 
 [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg?style=flat)](LICENSE.txt) [![Version](https://img.shields.io/npm/v/maplibre-gl?style=flat)](https://www.npmjs.com/package/maplibre-gl) [![CI](https://github.com/maplibre/maplibre-gl-js/actions/workflows/ci.yml/badge.svg)](https://github.com/maplibre/maplibre-gl-js/actions/workflows/ci.yml) [![PRs](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](https://opensource.org/licenses/BSD-3-Clause) [![codecov](https://codecov.io/gh/maplibre/maplibre-gl-js/branch/main/graph/badge.svg)](https://codecov.io/gh/maplibre/maplibre-gl-js)
 
-**[MapLibre GL JS](https://maplibre.org/maplibre-gl-js-docs/api/)** is an open-source library for publishing maps on your websites or webview based apps. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering. 
+**[MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/API/)** is an open-source library for publishing maps on your websites or webview based apps. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering. 
 
 It originated as an open-source fork of [mapbox-gl-js](https://github.com/mapbox/mapbox-gl-js), before their switch to a non-OSS license in December 2020. The library's initial versions (1.x) were intended to be a drop-in replacement for the Mapbox’s OSS version (1.x) with additional functionality, but have evolved a lot since then.
 
@@ -37,15 +37,15 @@ Enjoy the map!
 
 ## Documentation
 
-Full documentation for this library [is available here](https://maplibre.org/maplibre-gl-js-docs/api/).
+Full documentation for this library [is available here](https://maplibre.org/maplibre-gl-js/docs/API/).
 
-Check out the features through [examples](https://maplibre.org/maplibre-gl-js-docs/example/).
+Check out the features through [examples](https://maplibre.org/maplibre-gl-js/docs/examples/).
 
 | Showcases |      |
 | ---- | ---- |
-|![Display a map](https://maplibre.org/maplibre-gl-js-docs/assets/simple-map-800-1427cd84c8c693ead996f81b06e467bb.png)	|![Third party vector tile source](https://maplibre.org/maplibre-gl-js-docs/assets/third-party-800-72a3092888152ba26920ec0ba5aeacd0.png)	|
-|![Animate a series of images](https://maplibre.org/maplibre-gl-js-docs/assets/animate-images-800-522ec4f83d7988b2d6f23a0c1d5eb924.png)	|![Create a heatmap layer](https://maplibre.org/maplibre-gl-js-docs/assets/heatmap-layer-800-a23e44d9c1238315f191187c5c628719.png)	|
-|![3D buildings](https://maplibre.org/maplibre-gl-js-docs/assets/3d-buildings-800-18cda57800c107d1dee5f269bf7a12f2.png)	|![Visualize population density](https://maplibre.org/maplibre-gl-js-docs/assets/visualize-population-density-800-dc0290780f7b2842031bdf1b9347981a.png)	|
+|![Display a map](https://maplibre.org/maplibre-gl-js/docs/assets/simple-map-800-1427cd84c8c693ead996f81b06e467bb.png)	|![Third party vector tile source](https://maplibre.org/maplibre-gl-js/docs/assets/third-party-800-72a3092888152ba26920ec0ba5aeacd0.png)	|
+|![Animate a series of images](https://maplibre.org/maplibre-gl-js/docs/assets/animate-images-800-522ec4f83d7988b2d6f23a0c1d5eb924.png)	|![Create a heatmap layer](https://maplibre.org/maplibre-gl-js/docs/assets/heatmap-layer-800-a23e44d9c1238315f191187c5c628719.png)	|
+|![3D buildings](https://maplibre.org/maplibre-gl-js/docs/assets/3d-buildings-800-18cda57800c107d1dee5f269bf7a12f2.png)	|![Visualize population density](https://maplibre.org/maplibre-gl-js/docs/assets/visualize-population-density-800-dc0290780f7b2842031bdf1b9347981a.png)	|
 
 <br />
 
@@ -86,7 +86,7 @@ MapLibre GL JS v1 is completely backward compatible with Mapbox GL JS v1. This c
 
 ```
 
-Want an example? Have a look at the official [MapLibre GL JS Documentation](https://maplibre.org/maplibre-gl-js-docs/example/).
+Want an example? Have a look at the official [MapLibre GL JS Documentation](https://maplibre.org/maplibre-gl-js/docs/examples/).
 
 Use MapLibre GL JS bindings for React (https://visgl.github.io/react-map-gl/docs/get-started/get-started#using-with-a-mapbox-gl-fork) and Angular (https://github.com/maplibre/ngx-maplibre-gl). Find more at [awesome-maplibre](https://github.com/maplibre/awesome-maplibre).
 

package/build/generate-doc-images.ts

@@ -0,0 +1,73 @@
+import path from 'path';
+import fs from 'fs';
+import puppeteer from 'puppeteer';
+import packageJson from '../package.json' assert { type: 'json' };
+
+const exampleName = process.argv[2];
+const examplePath = path.resolve('test', 'examples');
+
+const browser = await puppeteer.launch({headless: exampleName === 'all'});
+
+const page = await browser.newPage();
+// set viewport and double deviceScaleFactor to get a closer shot of the map
+await page.setViewport({
+    width: 600,
+    height: 250,
+    deviceScaleFactor: 2
+});
+
+async function createImage(exampleName) {
+    // get the example contents
+    const html = fs.readFileSync(path.resolve(examplePath, `${exampleName}.html`), 'utf-8');
+
+    await page.setContent(html.replaceAll('../../dist', `https://unpkg.com/maplibre-gl@${packageJson.version}/dist`));
+
+    // Wait for map to load, then wait two more seconds for images, etc. to load.
+    await page
+        .waitForFunction('map.loaded()')
+        .then(async () => {
+            // Wait for 5 seconds on 3d model examples, since this takes longer to load.
+            const waitTime = exampleName.includes('3d-model') ? 5000 : 1500;
+            await new Promise((resolve) => {
+                console.log(`waiting for ${waitTime} ms`);
+                setTimeout(resolve, waitTime);
+            });
+        })
+        // map.loaded() does not evaluate to true within 3 seconds, it's probably an animated example.
+        // In this case we take the screenshot immediately.
+        .catch(() => {
+            console.log(`Timed out waiting for map load on ${exampleName}.`);
+        });
+
+    await page
+        .screenshot({
+            path: `./docs/assets/examples/${exampleName}.png`,
+            type: 'png',
+            clip: {
+                x: 0,
+                y: 0,
+                width: 600,
+                height: 250
+            }
+        })
+        .then(() => console.log(`Created ./docs/assets/examples/${exampleName}.png`))
+        .catch((err) => {
+            console.log(err);
+        });
+}
+
+if (exampleName === 'all') {
+    const allFiles = fs.readdirSync(examplePath).filter(f => f.endsWith('html'));
+    console.log(`Generating ${allFiles.length} images.`);
+    for (const file of allFiles) {
+        await createImage(file);
+    }
+} else if (exampleName) {
+    await createImage(exampleName);
+} else {
+    throw new Error(
+        '\n  Usage: npm run generate-images <file-name|all>\nExample: npm run generate-images 3d-buildings'
+    );
+}
+
+await browser.close();

package/build/generate-docs.ts

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import path from 'path';
+import typedocConfig from '../typedoc.json' assert {type: 'json'};
+import packageJson from '../package.json' assert {type: 'json'};
+
+type HtmlDoc = {
+    title: string;
+    description: string;
+    mdFileName: string;
+}
+
+function generateAPIIntroMarkdown(lines: string[]): string {
+    let intro = `# Intro
+
+This file is intended as a reference for the important and public classes of this API.
+We reccomend looking at the [expamples](../examples/index.md) as they will help you the most to start with MapLibre.
+
+Most of the classes wirtten here have an "Options" object for initialization, it is recommended to check which options exist. 
+
+`;
+    intro += lines.map(l => l.replace('../', './')).join('\n');
+    return intro;
+}
+
+function generateMarkdownForExample(title: string, description: string, file: string, htmlContent: string): string {
+    return `
+# ${title}
+
+${description}
+
+<iframe src="../${file}" width="100%" style="border:none; height:400px"></iframe>
+
+\`\`\`html
+${htmlContent}
+\`\`\`
+`;
+}
+
+function generateMarkdownIndexFileOfAllExamples(indexArray: HtmlDoc[]): string {
+    let indexMarkdown = '# Overview \n\n';
+    for (const indexArrayItem of indexArray) {
+        indexMarkdown += `
+## [${indexArrayItem.title}](./${indexArrayItem.mdFileName})
+
+![${indexArrayItem.description}](../assets/examples/${indexArrayItem.mdFileName!.replace('.md', '.png')})
+
+${indexArrayItem.description}
+`;
+    }
+    return indexMarkdown;
+}
+
+if (!fs.existsSync(typedocConfig.out)) {
+    throw new Error('Please run typedoc generation first!');
+}
+
+fs.rmSync(path.join(typedocConfig.out, 'README.md'));
+fs.rmSync(path.join(typedocConfig.out, 'modules.md'));
+// Intro file for the API
+const modulesFolder = path.join(typedocConfig.out, 'modules');
+const content = fs.readFileSync(path.join(modulesFolder, `${typedocConfig.internalModule}.md`), 'utf-8');
+let lines = content.split('\n');
+const classesLineIndex = lines.indexOf(lines.find(l => l.endsWith('Classes')) as string);
+lines = lines.splice(2, classesLineIndex - 2);
+const contentString = generateAPIIntroMarkdown(lines);
+fs.writeFileSync(path.join(typedocConfig.out, 'README.md'), contentString);
+
+// Examples manupilation
+const examplesDocsFolder = path.join('docs', 'examples');
+if (fs.existsSync(examplesDocsFolder)) {
+    fs.rmSync(examplesDocsFolder, {recursive: true, force: true});
+}
+fs.mkdirSync(examplesDocsFolder);
+const examplesFolder = path.join('test', 'examples');
+const files = fs.readdirSync(examplesFolder).filter(f => f.endsWith('html'));
+const maplibreUnpgk = `https://unpkg.com/maplibre-gl@${packageJson.version}/`;
+const indexArray = [] as HtmlDoc[];
+for (const file of files) {
+    const htmlFile = path.join(examplesFolder, file);
+    let htmlContent = fs.readFileSync(htmlFile, 'utf-8');
+    htmlContent = htmlContent.replace(/\.\.\/\.\.\//g, maplibreUnpgk);
+    htmlContent = htmlContent.replace(/-dev.js/g, '.js');
+    const htmlContentLines = htmlContent.split('\n');
+    const title = htmlContentLines.find(l => l.includes('<title'))?.replace('<title>', '').replace('</title>', '').trim();
+    const description = htmlContentLines.find(l => l.includes('og:description'))?.replace(/.*content=\"(.*)\".*/, '$1');
+    fs.writeFileSync(path.join(examplesDocsFolder, file), htmlContent);
+    const mdFileName = file.replace('.html', '.md');
+    indexArray.push({
+        title: title!,
+        description: description!,
+        mdFileName
+    });
+    const exampleMarkdown = generateMarkdownForExample(title, description, file, htmlContent);
+    fs.writeFileSync(path.join(examplesDocsFolder, mdFileName), exampleMarkdown);
+}
+
+const indexMarkdown = generateMarkdownIndexFileOfAllExamples(indexArray);
+fs.writeFileSync(path.join(examplesDocsFolder, 'index.md'), indexMarkdown);
+
+console.log('Docs generation completed, to see it in action run\n docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material');

package/build/generate-struct-arrays.ts

@@ -19,9 +19,9 @@ import rasterBoundsAttributes from '../src/data/raster_bounds_attributes';
 import circleAttributes from '../src/data/bucket/circle_attributes';
 import fillAttributes from '../src/data/bucket/fill_attributes';
 import fillExtrusionAttributes from '../src/data/bucket/fill_extrusion_attributes';
-import lineAttributes from '../src/data/bucket/line_attributes';
-import lineAttributesExt from '../src/data/bucket/line_attributes_ext';
-import patternAttributes from '../src/data/bucket/pattern_attributes';
+import {lineLayoutAttributes} from '../src/data/bucket/line_attributes';
+import {lineLayoutAttributesExt} from '../src/data/bucket/line_attributes_ext';
+import {patternAttributes} from '../src/data/bucket/pattern_attributes';
 // symbol layer specific arrays
 import {
     symbolLayoutAttributes,
@@ -144,8 +144,8 @@ const layoutAttributes = {
     fill: fillAttributes,
     'fill-extrusion': fillExtrusionAttributes,
     heatmap: circleAttributes,
-    line: lineAttributes,
-    lineExt: lineAttributesExt,
+    line: lineLayoutAttributes,
+    lineExt: lineLayoutAttributesExt,
     pattern: patternAttributes
 };
 for (const name in layoutAttributes) {
@@ -236,7 +236,6 @@ function emitStructArrayLayout(locals) {
 
     output.push(
         ` *
- * @private
  */
 class ${structArrayLayoutClass} extends StructArray {`);
 
@@ -349,7 +348,8 @@ function emitStructArray(locals) {
 
     if (includeStructAccessors && !useComponentGetters) {
         output.push(
-            `class ${structTypeClass} extends Struct {
+            `/** */
+class ${structTypeClass} extends Struct {
     _structArray: ${structArrayClass};`);
 
         for (const {name, member, component} of components) {
@@ -384,9 +384,7 @@ export type ${structTypeClass.replace('Struct', '')} = ${structTypeClass};
     } // end 'if (includeStructAccessors)'
 
     output.push(
-        `/**
- * @private
- */
+        `/** */
 export class ${structArrayClass} extends ${structArrayLayoutClass} {`);
 
     if (useComponentGetters) {
@@ -407,8 +405,7 @@ export class ${structArrayClass} extends ${structArrayLayoutClass} {`);
         output.push(
             `    /**
      * Return the ${structTypeClass} at the given location in the array.
-     * @param {number} index The index of the element.
-     * @private
+     * @param index The index of the element.
      */
     get(index: number): ${structTypeClass} {
         return new ${structTypeClass}(this, index);