ol-stac 1.0.0-beta.6 → 1.0.0-beta.7

package/.eslintignore

@@ -0,0 +1,2 @@
+examples/resources/
+config/jsdoc/api/template/static/scripts/

package/.github/workflows/deploy.yml

@@ -0,0 +1,67 @@
+name: Deploy Website
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*.*.*'
+
+concurrency:
+  group: "deploy"
+
+jobs:
+  deploy-branch:
+    if: startsWith(github.ref, 'refs/heads/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: npm ci
+      - name: Build Website
+        run: ./tasks/build-website.sh -l $(node tasks/get-latest-release.js)
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+          clean: false
+      - name: Commit to GitHub Pages
+        run: |
+          cp -r build/site/* .
+          if [ -n "$(git status --porcelain)" ]; then
+            git config user.name "$(git --no-pager log --format=format:'%an' -n 1)"
+            git config user.email "$(git --no-pager log --format=format:'%ae' -n 1)"
+            git add .
+            git commit -m "Website updates"
+            git push origin gh-pages
+          fi
+  deploy-tag:
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: npm ci
+      - name: Assert Latest Release
+        run: node tasks/newest-tag.js --tag ${GITHUB_REF_NAME}
+      - name: Build Website
+        run: ./tasks/build-website.sh -l ${GITHUB_REF_NAME} -v ${GITHUB_REF_NAME}
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+          clean: false
+      - name: Commit to GitHub Pages
+        run: |
+          cp -r build/site/* .
+          if [ -n "$(git status --porcelain)" ]; then
+            git config user.name "$(git --no-pager log --format=format:'%an' -n 1)"
+            git config user.email "$(git --no-pager log --format=format:'%ae' -n 1)"
+            git add .
+            git commit -m "Website updates"
+            git push origin gh-pages
+          fi

package/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-tag:
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install dependencies
+        run: npm ci
+      - name: Assert Latest Release
+        run: node tasks/newest-tag.js --tag ${GITHUB_REF_NAME}
+      - name: Publish
+        run: |
+          npm run build-package
+          cd build/ol
+          npm publish --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Create Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - name: Install dependencies
+        run: npm ci
+      - name: Build Release Assets
+        run: ./tasks/build-website.sh -l ${GITHUB_REF_NAME} -v ${GITHUB_REF_NAME}
+      - name: Create Release
+        run: node tasks/create-release.js --token ${{secrets.GITHUB_TOKEN}} --tag ${GITHUB_REF_NAME} --package build/${GITHUB_REF_NAME}-package.zip --site build/${GITHUB_REF_NAME}-site.zip

package/.github/workflows/test.yml

@@ -0,0 +1,82 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  CI: true
+
+permissions:
+  contents: read
+
+jobs:
+  pretest:
+    name: Pre-Test
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v3
+
+      - name: Set Node.js Version
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Run Tests
+        run: npm run pretest
+
+  browser:
+    name: Browser
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v3
+
+      - name: Set Node.js Version
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Run Tests
+        run: npm run test-browser
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v3
+
+      - name: Set Node.js Version
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Build the Package
+        run: npm run build-package

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0-beta.7] - 2024-01-26
+
+- Added an option to hide footprints (geometry/bounding box) by default
+- Added support for image formats in WMS and WMTS
+- Expose `SourceType` as public API
+- Removed note about Firefox issues in the examples
+
+## [1.0.0-beta.6] - 2023-08-28
+
+- OpenLayers is now a peer dependency
+- Add support for PMTiles (via Web Map Links extension)
+- New general purpose option `getSourceOptions(type, options, ref)` to customize source options.
+   It also applies to all web-map-link source options now.
+   It replaces:
+   - `getGeoTIFFSourceOptions(options, ref)`
+   - `getImageStaticSourceOptions(options, ref)`
+   - `getXYZSourceOptions(options, ref)`
+- Added `SourceType` enum for `getSourceOptions`
+
+## [1.0.0-beta.5] - 2023-08-23
+
+- Don't enforce the nodata value to be `NaN` if not present in STAC metadata
+
+## [1.0.0-beta.4] - 2023-08-22
+
+- Fix the default entry point (you can now really use `import STAC from 'ol-stac';`)
+
+## [1.0.0-beta.3] - 2023-08-22
+
+- Pass `properties` option to the LayerGroup.
+
+## [1.0.0-beta.2] - 2023-08-22
+
+- Move the `stacUtils.js` from `ol/layer` to `ol-stac/utils.js`
+- Provide a default entry point (you can now use `import STAC from 'ol-stac';`)
+- Documentation improvements
+
+## [1.0.0-beta.1] - 2023-08-22
+
+- First release
+
+[Unreleased]: <https://github.com/stac-extensions/contacts/compare/v1.0.0-beta.7...HEAD>
+[1.0.0-beta.6]: <https://github.com/stac-extensions/contacts/compare/v1.0.0-beta.6...v1.0.0-beta.7>
+[1.0.0-beta.6]: <https://github.com/stac-extensions/contacts/compare/v1.0.0-beta.5...v1.0.0-beta.6>
+[1.0.0-beta.5]: <https://github.com/stac-extensions/contacts/compare/v1.0.0-beta.4...v1.0.0-beta.5>
+[1.0.0-beta.4]: <https://github.com/stac-extensions/contacts/compare/v1.0.0-beta.3...v1.0.0-beta.4>
+[1.0.0-beta.3]: <https://github.com/stac-extensions/contacts/compare/v1.0.0-beta.2...v1.0.0-beta.3>
+[1.0.0-beta.2]: <https://github.com/stac-extensions/contacts/compare/v1.0.0-beta.1...v1.0.0-beta.2>
+[1.0.0-beta.1]: <https://github.com/stac-extensions/contacts/tree/v1.0.0-beta.1>

package/DEVELOPING.md

@@ -0,0 +1,104 @@
+# Developing
+
+## Setting up development environment
+
+You will start by [forking](https://github.com/m-mohr/ol-stac/fork) the OL STAC repository.
+
+### Installing dependencies
+
+The minimum requirements are:
+
+* Git
+* [Node.js](https://nodejs.org/) (version 16 and above)
+
+The executables `git` and `node` should be in your `PATH`.
+
+To install the project dependencies run
+
+```shell
+npm install
+```
+
+
+## Style guidelines
+
+We use [ESLint](https://eslint.org/) rules to ensure a consistent coding style and catch potential bugs.  ESLint and the rules used by the project are installed as part of the development dependencies in the step above – so you don't need to have any additional executables installed globally.
+
+When you submit a pull request, the styling rules are enforced by running the `npm run lint` task.  This happens as part of an automated workflow, so you don't need to run it yourself.  However, it can be useful to run the `npm run lint` task before submitting a pull request so that you can fix any styling issues ahead of time.
+
+The best way to conform with the style guidelines is to configure your editor to detect the ESLint configuration from the repository's `package.json` file.  See the [ESLint integration documentation](https://eslint.org/docs/latest/use/integrations) for details on configuring your editor.  If you don't already have a preferred editor that is capable of running ESLint rules, we recommend using [VS Code](https://code.visualstudio.com/) with the [ESLint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
+
+In addition to having your editor warn you when the style guidelines are not being followed, you can set things up so many of the violations are automatically fixed.  This saves you from having to think about tedious things like spacing and whitespace while developing.  Using the ESLint plugin for VS Code, you can add the following to your settings to automatically fix issues when you save a file:
+
+```json
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll": true
+  }
+}
+```
+
+
+## Running examples
+
+To run the examples you first need to start the dev server:
+
+```shell
+npm run serve-examples
+```
+
+Then, load <http://localhost:8080/> in your browser.
+
+
+## Running tests
+
+To run the tests once:
+
+```shell
+npm test
+```
+
+To run the tests continuously during development:
+
+```shell
+npm run karma
+```
+
+
+## Adding examples
+
+Adding functionality often implies adding one or several examples. This
+section provides explanations related to adding examples.
+
+The examples are located in the `examples` directory. Adding a new example
+implies creating two or three files in this directory, an `.html` file, a `.js`
+file, and, optionally, a `.css` file.
+
+You can use `simple.js` and `simple.html` as templates for new examples.
+
+
+## Linking Package
+
+The `ol-stac` package is published from the `build/ol` folder of the `ol-stac` repo.
+
+After you've cloned the `ol-stac` repo locally run the `npm build-package` to prepare the build then use the `npm link` command to connect it your project.
+
+Below is an example of how to build and link it to `sample-project`.
+
+```shell
+cd ol-stac
+npm run build-package
+cd build/ol
+npm link
+cd /sample-project
+npm link ol-stac
+```
+
+To remove the link run the following commands
+
+```shell
+cd sample-project
+npm unlink --no-save ol-stac
+cd ../ol-stac
+npm unlink
+```

package/config/jsdoc/api/conf.json

@@ -0,0 +1,37 @@
+{
+  "opts": {
+    "recurse": true,
+    "template": "config/jsdoc/api/template"
+  },
+  "tags": {
+    "allowUnknownTags": true
+  },
+  "source": {
+    "includePattern": ".+\\.js$",
+    "excludePattern": "(^|\\/|\\\\)_",
+    "include": [
+      "src/ol"
+    ]
+  },
+  "plugins": [
+    "jsdoc-plugin-intersection",
+    "config/jsdoc/plugins/markdown.cjs",
+    "jsdoc-plugin-typescript",
+    "config/jsdoc/plugins/inline-options.cjs",
+    "config/jsdoc/plugins/events.cjs",
+    "config/jsdoc/plugins/api.cjs",
+    "config/jsdoc/plugins/default-export.cjs"
+  ],
+  "typescript": {
+    "moduleRoot": "src"
+  },
+  "templates": {
+    "cleverLinks": true,
+    "monospaceLinks": true,
+    "default": {
+      "outputSourceFiles": false
+    },
+    "applicationName": "OL STAC"
+  },
+  "jsVersion": 180
+}

package/config/jsdoc/api/index.md

@@ -0,0 +1,3 @@
+This is the API documentation for `ol-stac`.
+
+The class you likely want to look at is the <a href="module-ol_layer_STAC-STACLayer.html">STACLayer</a> class, which is an advanced version of an OpenLayers LayerGroup.

package/config/jsdoc/api/readme.md

@@ -0,0 +1,61 @@
+# API Documentation
+
+This directory contains configuration (`conf.json`), static content (`index.md`), template (`template/`) and plugins (`plugins/`) for the [JSDoc3](https://jsdoc.app/) API generator.
+
+## Documenting the source code
+
+JSDoc annotations are used for metadata used by the compiler, for defining the user facing API, and for user documentation.
+
+In the simplest case, a JSDoc block can look like this:
+```js
+/**
+ * Add the given control to the map.
+ * @param {ol.control.Control} control Control.
+ * @api
+ */
+ol.Map.prototype.addControl = function(control) {
+  // ...
+};
+```
+The first line is text for the user documentation. This can be long, and it can
+contain Markdown.
+
+The second line tells the Closure compiler the type of the argument.
+
+The third line (`@api`) marks the method as part of the api and thus exportable. Without such an api annotation, the method will not be documented in the generated API documentation. Symbols without an api annotation will also not be exportable.
+
+In general, `@api` annotations should never be used on abstract methods (only on their implementations).
+
+### Events
+
+Events are documented using `@fires` and `@event` annotations:
+```js
+/**
+ * Constants for event names.
+ * @enum {string}
+ */
+ol.MapBrowserEventType = {
+  /**
+   * A true single click with no dragging and no double click. Note that this
+   * event is delayed by 250 ms to ensure that it is not a double click.
+   * @event ol.MapBrowserEvent#singleclick
+   * @api
+   */
+  SINGLECLICK: 'singleclick',
+  // ...
+};
+```
+Note the value of the `@event` annotation. The text before the hash refers to the event class that the event belongs to, and the text after the hash is the type of the event.
+
+To document which events are fired by a class or method, the `@fires` annotation is used:
+```js
+/**
+ * @fires ol.MapBrowserEvent
+ * @fires ol.MapEvent
+ * @fires ol.render.Event
+ * ...
+ */
+ol.Map = function(options) {
+  // ...
+};
+```

package/config/jsdoc/api/template/README.md

@@ -0,0 +1,3 @@
+This template is based on the [Jaguar](https://github.com/davidshimjs/jaguarjs/tree/master/docs/templates/jaguar) template. [JaguarJS](https://github.com/davidshimjs/jaguarjs) is licensed under the [LGPL license](https://github.com/davidshimjs/jaguarjs/tree/master/LICENSE).
+
+The default template for JSDoc 3 uses: [the Salty Database library](https://www.npmjs.com/package/@jsdoc/salty) and the [Underscore Template library](https://underscorejs.org/#template).