@trailstash/ultra 3.0.0-dev

package/docs/further-reading.md

@@ -0,0 +1,15 @@
+Here are some more resources on Overpass Ultra:
+
+## OSM Wiki
+
+[Overpass Ultra on the OpenStreetMap Wiki](https://wiki.openstreetmap.org/wiki/Overpass_Ultra)
+
+## Diary Entries
+
+- [Introducing Overpass Ultra v2](https://www.openstreetmap.org/user/dpschep/diary/403263)
+- [Some Overpass Ultra Updates](https://www.openstreetmap.org/user/dpschep/diary/404330)
+
+## Third party blog posts
+
+- [Ultraschnell: Overpass Ultra](https://geoobserver.wordpress.com/2024/01/25/ultraschnell-overpass-ultra/) 🇩🇪
+- [Overpass Ultra & MapLibre: Heatmaps](https://geoobserver.wordpress.com/2024/02/23/overpass-ultra-maplibre-heatmaps/) 🇩🇪

package/docs/index.md

@@ -0,0 +1,55 @@
+# Introduction
+
+<img alt="powered by Overpass API" style="float: right" src="https://wiki.openstreetmap.org/w/images/b/b3/Powered_by_Overpass_API.png">
+
+[Overpass Ultra](https://overpass-ultra.us) is a web-application made to simplify making maps with [MapLibre GL
+JS](https://maplibre.org) and [OpenStreetMap](https://openstreetmap.org) data, powered by the
+[Overpass API](https://overpass-api.de/) and
+[`osmtogeojson`](https://github.com/tyrasd/osmtogeojson)
+
+The customization of the map comply with an [extended](https://overpass-ultra.us/docs/style#ultra-maplibre-styles) version
+of the the [MapLibre Style Spec](https://maplibre.org/maplibre-style-spec/).
+
+## Documentation
+
+The documentation for Overpass Ultra is available at <a target="_blank" href="https://overpass-ultra.us/docs/">overpass-ultra.us/docs</a>
+
+## Overpass Queries
+
+Overpass API allows to query for OSM data by your own search criteria. For this purpose, it has a
+specifically crafted query language: [Overpass
+QL](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL)
+
+In addition to regular Overpass API queries one can use `{{bbox}}` to specify the bounding box
+coordinates of the current map view.
+
+## Configuration
+
+Various aspects of Overpass Ultra, such as styling and the Overpass API server to use, can be
+configured via [YAML front-matter](https://overpass-ultra.us/docs/yaml).
+
+## Styling
+
+Overpass Ultra supports styling using the [MapLibre Style
+Specification](https://maplibre.org/maplibre-style-spec/).
+
+See the [Styling](https://overpass-ultra.us/docs/style) section for more information.
+
+## About
+
+Overpass Ultra is built by Daniel Schep.
+
+You can contact me on [Mastodon](https://mapstodon.space/@trailstash).
+
+## Feedback, Bug Reports, Feature Requests
+
+While Overpass Ultra has been in development for a while, it should still be considered
+experimental.
+
+If you would like to report a bug or provide other feedback, please do so in the project's
+[Issue Tracker](https://gitlab.com/trailstash/overpass-ultra/-/issues).
+
+## Source Code</h4>
+
+The [source code](https://gitlab.com/trailstash/overpass-ultra) of this application is released under the
+[MIT license](https://gitlab.com/trailstash/overpass-ultra/-/blob/master/LICENSE).

package/docs/overrides/partials/integrations/analytics/custom.html

@@ -0,0 +1,11 @@
+<script
+  async
+  defer
+  src="https://sa.trailsta.sh/latest.js"
+></script>
+<noscript
+  ><img
+    src="https://sa.trailsta.sh/noscript.gif"
+    alt=""
+    referrerpolicy="no-referrer-when-downgrade"
+/></noscript>

package/docs/query-shortcuts.md

@@ -0,0 +1,21 @@
+In order to allow for querying Overpass with the extents of the MapLibre viewport, Overpass Ultra
+replaces any occurences of `{{bbox}}` in the query with the bounding box in the format expected by
+the Overpass API.
+
+For example:
+```
+[bbox:{{bbox}}];
+nwr[shop];
+out center;
+```
+
+### Other formats
+If you need to specify the coordinates in a different order, you can use the following shortcuts
+for the min and max of both lattitude and longitude:
+
+* `{{south}}`
+* `{{north}}`
+* `{{east}}`
+* `{{west}}`
+
+[Example](./Examples/alt-bbox-format.md)

package/docs/style.md

@@ -0,0 +1,120 @@
+# Styling
+
+The MapLibre styling can be attached to a query written in the Overpass-QL query language via the
+`style:` key of the [YAML front-matter](./yaml.md).
+
+```
+---
+style: ... your MapLibre style here ...
+---
+... your overpass query here ...
+```
+
+The value of the style: key can contain:
+
+ * a URL to a MapLibre style
+ * a full MapLibre style object
+ * a Ultra MapLibre style
+
+## Ultra MapLibre styles
+
+In order to simplify the use of MapLibre styles, Overpass Ultra implements a number of features.
+
+### Query result styling
+
+In order to allow for easy styling of the query results, Overpass Ultra allows you to specify a
+style with only the layer for your query results.
+
+For example, to render query results with a purple MapLibre
+[circle](https://maplibre.org/maplibre-style-spec/layers/#circle) layer:
+
+```
+---
+style:
+  layers:
+    - type: circle
+      paint:
+        circle-color: purple
+---
+nwr[shop]({{bbox}}); out center;
+```
+
+#### Extending a specific basemap style
+
+To specify what style to add result styling to, use the `extends` key.
+
+For example, to render the purple circles on the [Protomaps]() light basemap:
+
+```
+---
+style:
+  extends: https://styles.trailsta.sh/protomaps-light.json
+  layers:
+    - type: circle
+      paint:
+        circle-color: purple
+---
+nwr[shop]({{bbox}}); out center;
+```
+
+### Layer `source` & `id`
+In the above examples, the layer definitions are lacking both source and layers keys.
+
+Layers don't need to specify an ID, and if the source is not specified, it will be set to to the
+source containting the query results.
+
+### Automatic `paint` and `layer` keys
+In order to reduce the mental overhead of remember what keys are
+[`paint`](https://maplibre.org/maplibre-style-spec/layers/#paint) options and which are
+[`layout`](https://maplibre.org/maplibre-style-spec/layers/#layout) options, Overpass Ultra will
+automatically move them from the layer object into the appropriate options object.
+
+For example, the above purple circle layer can be implemented as:
+
+```
+---
+style:
+  layers:
+    - type: circle
+      circle-color: purple
+---
+nwr[shop]({{bbox}}); out center;
+```
+
+### Sandwiching layers
+In order to place your layers below existing style layers, you can use the `beforeLayerId:` key. 
+
+[Example](./Examples/bike-infra.md)
+
+## PNG sprites via HTTPS
+In order to facilitate adding icons to the map that don't exist in the basemap's
+[sprites](),
+if `icon-image` is set to an HTTPS URL to a PNG image, Overpass Ultra will automatically download
+it and add it to the Map's images.
+
+[Example](./MapLibre-Examples/add-image.md)
+
+## Bundled Sprites
+In order to simplify the creation of POI maps, Overpass Ultra bundles the
+[Maki](https://github.com/mapbox/maki) and [Temaki](https://github.com/rapideditor/temaki) sprites
+and adds them to your style as [SDFs](https://docs.mapbox.com/help/troubleshooting/using-recolorable-images-in-mapbox-maps/)
+allowing for easy styling of icons.
+
+Example:
+
+```
+---
+style:
+  layers:
+    - type: symbol
+      icon-image: maki:bus
+      icon-color: white
+      icon-halo-color: '#6486f5'
+      icon-halo-width: 5
+---
+```
+
+## Fallback fontstack
+Since not all MapLibre styles have the same
+[glyphs](https://maplibre.org/maplibre-style-spec/glyphs/), Overpass Ultra will default to using
+Noto Sans Regular if the speficied(or default) fontstack is not available.

package/docs/url-parameters.md

@@ -0,0 +1,45 @@
+# URL Hash Parameters
+
+You use the following query string parameters as a hash to instruct Overpass Ultra to set certain properties on startup (such as the query or the map location).
+
+## `query` <small>(URL-encoded string)</small>
+
+This sets the query to the given string.
+
+Example: [http://overpass-ultra.us/#query=node%5B%22amenity%22%3D%22drinking_water%22%5D(%7B%7Bbbox%7D%7D)%3B%0Aout%3B](http://overpass-ultra.us/#query=node%5B%22amenity%22%3D%22drinking_water%22%5D(%7B%7Bbbox%7D%7D)%3B%0Aout%3B)
+
+### Loading Gists
+
+You can load a query from a Gist by using a string prefixed with `gist:`
+
+Example: [http://overpass-ultra.us/#query=gist:8ecb8ba0a0136f4f0dbc36de82061de4](http://overpass-ultra.us/#query=gist:8ecb8ba0a0136f4f0dbc36de82061de4)
+
+### Loading URLs
+
+You can load a query from any url by using a string prefixed with `url:`
+
+Example: [http://overpass-ultra.us/#query=url:https%3A%2F%2Fgist.githubusercontent.com%2Fdschep%2F8ecb8ba0a0136f4f0dbc36de82061de4%2Fraw%2F40ce5053cc664984d677bca20a2a2d3371ce09b0%2Fgistfile1.txt](http://overpass-ultra.us/#query=url:https%3A%2F%2Fgist.githubusercontent.com%2Fdschep%2F8ecb8ba0a0136f4f0dbc36de82061de4%2Fraw%2F40ce5053cc664984d677bca20a2a2d3371ce09b0%2Fgistfile1.txt)
+
+## `q` <small>(lz-string-compressed string)</small>
+
+This sets the query to the given Base64-encoded lz-string string.
+
+Example: [http://overpass-ultra.us/#q=NoIxHsA8C4G9bFAvkgugbgFAHcCGBPYACwEsBzIvfAXgAdcAXIjTcAVwYAIyBTcAW3RA](http://overpass-ultra.us/#q=NoIxHsA8C4G9bFAvkgugbgFAHcCGBPYACwEsBzIvfAXgAdcAXIjTcAVwYAIyBTcAW3RA)
+
+## `m` <small>(z/x/y viewport)</small>
+
+Sets the map center coordinates and zoom level.
+
+Example: [http://overpass-ultra.us/#m=14.64/-33.8842/151.2077](http://overpass-ultra.us/#m=14.64/-33.8842/151.2077)
+
+## `run`
+
+Runs the query immediately after startup.
+
+Example: [http://overpass-ultra.us/#run&query=node%5B%22amenity%22%3D%22drinking_water%22%5D(%7B%7Bbbox%7D%7D)%3B%0Aout%3B&m=14.64/-33.8842/151.2077](http://overpass-ultra.us/#run&query=node%5B%22amenity%22%3D%22drinking_water%22%5D(%7B%7Bbbox%7D%7D)%3B%0Aout%3B&m=14.64/-33.8842/151.2077)
+
+## `map`
+
+Runs the query as a customizable interactive map.
+
+Example: [http://overpass-ultra.us/#map&query=node%5B%22amenity%22%3D%22drinking_water%22%5D(%7B%7Bbbox%7D%7D)%3B%0Aout%3B&m=14.64/-33.8842/151.2077 ](http://overpass-ultra.us/#map&query=node%5B%22amenity%22%3D%22drinking_water%22%5D(%7B%7Bbbox%7D%7D)%3B%0Aout%3B&m=14.64/-33.8842/151.2077 )

package/docs/yaml.md

@@ -0,0 +1,117 @@
+# YAML front-matter config
+
+The real power of Overpass Ultra lies in it's easy configuration of MapLibre with the a query's
+[YAML front-matter](https://jekyllrb.com/docs/front-matter/).
+
+## `style`
+
+Customize the MapLibre style. See [Styling](./Style.md) for more information.
+
+Example: 
+```
+---
+style: https://example.com/style.json
+---
+```
+
+## `server`
+
+Use a different Overpass API server.
+
+Example: 
+```
+---
+server:  https://overpass.private.coffee/api/
+---
+```
+
+<small>Only applies to Overpass queries.</small>
+
+## `popupTemplate`
+
+Customize the interactive popup with a [LiquidJS]() template. Or set it to `false` to disable the
+interactive popup.
+
+```
+---
+popupTemplate: "{{type}} {{id}} - {{tags.name}}"
+---
+```
+
+## `type`
+
+Specify the type of source in the query.
+
+**Default:** `overpass`
+
+### `overpass`
+An [Overpass QL](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL) query. Results
+converted into a [GeoJSON source](https://maplibre.org/maplibre-style-spec/sources/#geojson) with
+[`osmtogeojson`](https://github.com/tyrasd/osmtogeojson).
+
+### `osmxml`
+An [OSM XML](https://wiki.openstreetmap.org/wiki/OSM_XML) document or a URL to one. Converted into
+a [GeoJSON source](https://maplibre.org/maplibre-style-spec/sources/#geojson) with
+[`osmtogeojson`](https://github.com/tyrasd/osmtogeojson).
+
+### `osmjson`
+An [OSM JSON](https://wiki.openstreetmap.org/wiki/OSM_JSON) document or a URL to one. Converted
+into a [GeoJSON source](https://maplibre.org/maplibre-style-spec/sources/#geojson) with
+[`osmtogeojson`](https://github.com/tyrasd/osmtogeojson).
+
+### `geojson`
+A JSON-encoded GeoJSON object or a URL to a GeoJSON file.
+
+### `raster`
+A line delimited list of [tile URLs](https://maplibre.org/maplibre-style-spec/sources/#tiles_1) for
+a [raster source](https://maplibre.org/maplibre-style-spec/sources/#raster) or a [TileJSON
+url](https://maplibre.org/maplibre-style-spec/sources/#url_1)
+
+### `vector`
+A line delimited list of [tile URLs](https://maplibre.org/maplibre-style-spec/sources/#tiles_2) for
+a [vector source](https://maplibre.org/maplibre-style-spec/sources/#vector) or a [TileJSON
+url](https://maplibre.org/maplibre-style-spec/sources/#url_2)
+
+## `options`
+
+When an Overpass Ultra query is run in "interactive map" mode, you can specify the
+[`MapOptions`](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/)
+that are passed to the MapLibre constructor.
+
+For example, you can use this to fit to bounds rather than relying on the z/x/y URL parameters,
+making for a more consistent experience across screen sizes. EG:
+
+```
+---
+options:
+  bounds: [-77.64656066894544,37.577235791111384,-76.92558288574232,38.13563674858875]
+---
+```
+
+## `controls`
+When an Overpass Ultra query is run in "interactive map" mode, you can specify controls to be added to the map with the `controls` key
+in the YAML-front matter. The key should contain a list of objects. Each object must specify a `type` key containing the 
+name of a control present in MapLibre. It can optionally contain an `options` key who's contents are passed to the
+control's constructor and a `position` key that is passed to
+[`map.addControl`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#addcontrol).
+
+For example, to add a NavigationControl to your map:
+```
+---
+controls:
+  - type: NavigationControl
+    options:
+      visualizePitch: true
+    position: bottom-left
+---
+```
+
+## `querySources`
+
+Specify which sources can be queried by mouse-click
+
+```
+---
+querySources: [ultra] # this is the default
+---
+```

package/index.js

@@ -0,0 +1,53 @@
+import { Protocol } from "pmtiles";
+import MapLibre from "@trailstash/maplibre-component";
+import maplibregl from "maplibre-gl";
+
+import { normalizeCSS } from "./lib/normalize.js";
+import FallbackGlyphProtocol from "./lib/glyphFallback.js";
+
+import { UltraLoader } from "./components/ultra-loader.js";
+import { UltraMap } from "./components/ultra-map.js";
+import { UltraIDE } from "./components/ultra-ide.js";
+import { CodeEditor } from "./components/code-editor.js";
+import { NavBar } from "./components/nav-bar.js";
+import { RunButton } from "./components/run-button.js";
+import { DownloadButton } from "./components/download-button.js";
+import { StylePicker } from "./components/style-picker.js";
+import { ShareModal as ShareButton } from "./components/share-modal.js";
+import { HelpModal } from "./components/help-modal.js";
+import { FSButton } from "./components/fs-button.js";
+import { FontAwesomeIcon } from "./components/fontawesome-icon.js";
+import { ButtonModal } from "./components/button-modal.js";
+import { MapPopup } from "./components/map-popup.js";
+
+// style
+document.adoptedStyleSheets.push(normalizeCSS);
+
+// maplibre plugins
+const protocol = new Protocol();
+maplibregl.addProtocol("pmtiles", protocol.tile);
+
+maplibregl.setRTLTextPlugin("./mapbox-gl-rtl-text@0.2.3.js", true);
+
+const fallbackGlyphsProtocol = new FallbackGlyphProtocol();
+maplibregl.addProtocol(FallbackGlyphProtocol.name, fallbackGlyphsProtocol.tile);
+
+// register element
+customElements.define("code-editor", CodeEditor);
+customElements.define("map-libre", MapLibre);
+customElements.define("nav-bar", NavBar);
+customElements.define("run-button", RunButton);
+customElements.define("download-button", DownloadButton);
+customElements.define("share-button", ShareButton);
+customElements.define("help-modal", HelpModal);
+customElements.define("style-picker", StylePicker);
+customElements.define("fs-button", FSButton);
+customElements.define("fa-icon", FontAwesomeIcon);
+customElements.define("button-modal", ButtonModal);
+customElements.define("map-popup", MapPopup);
+customElements.define("ultra-map", UltraMap);
+customElements.define("ultra-ide", UltraIDE);
+customElements.define("ultra-loader", UltraLoader);
+
+// reload on hash changes
+addEventListener("hashchange", () => window.location.reload());

package/lib/base.css

@@ -0,0 +1,12 @@
+/* full-page */
+html,
+body {
+  width: 100%;
+  height: 100%;
+  display: flex;
+}
+
+/* font */
+body {
+  font-family: sans-serif;
+}

package/lib/bounds.js

@@ -0,0 +1,8 @@
+export function setQueryBounds(query, bounds) {
+  return query
+    .replace(/{{bbox}}/g, `{{south}},{{west}},{{north}},{{east}}`)
+    .replace(/{{south}}/g, bounds.getSouth())
+    .replace(/{{west}}/g, bounds.getWest())
+    .replace(/{{north}}/g, bounds.getNorth())
+    .replace(/{{east}}/g, bounds.getEast());
+}

package/lib/dom.js

@@ -0,0 +1,21 @@
+// DOM generation helpers
+
+export const h = (elName, attrs, ...children) => {
+  const el = document.createElement(elName);
+  for (const key in attrs) {
+    if (key in el) {
+      el[key] = attrs[key];
+    } else {
+      el.setAttribute(key, attrs[key]);
+    }
+  }
+  if (children.length === 1 && typeof children[0] === "string") {
+    el.innerHTML = children[0];
+  } else {
+    for (const child of children) {
+      el.appendChild(child);
+    }
+  }
+  return el;
+};
+export const t = (text) => document.createTextNode(text);

package/lib/glyphFallback.js

@@ -0,0 +1,31 @@
+export class Protocol {
+  static name = "glyphs";
+  static makeURL = (url) => {
+    const params = new URLSearchParams();
+    if (url) {
+      params.set("url", url);
+    }
+    return `${Protocol.name}://origin/{fontstack}/{range}?${params.toString()}`;
+  };
+  tile = async (params) => {
+    const url = new URL(params.url);
+    let resp;
+    const [fontstack, range] = url.pathname.split("/").slice(-2);
+    if (url.searchParams.has("url")) {
+      resp = await fetch(
+        url.searchParams
+          .get("url")
+          .replace("{fontstack}", fontstack)
+          .replace("{range}", range),
+      );
+    }
+    if (!resp || !resp.ok) {
+      resp = await fetch(`./font/${range}.pbf`);
+    }
+    if (resp) {
+      return { data: await resp.arrayBuffer() };
+    }
+  };
+}
+
+export default Protocol;

package/lib/localStorage.js

@@ -0,0 +1,34 @@
+export const localStorage = {
+  getItem: (key) => {
+    try {
+      return JSON.parse(window.localStorage.getItem(key));
+    } catch {
+      return null;
+    }
+  },
+  setItem: (key, value) => {
+    try {
+      return window.localStorage.setItem(key, JSON.stringify(value));
+    } catch {
+      return;
+    }
+  },
+};
+
+export default localStorage;
+
+export const optionsFromStorage = () => {
+  const options = {};
+  const center = localStorage.getItem("mapCenter");
+  const zoom = localStorage.getItem("mapZoom");
+  if (center) {
+    options.center = center;
+  }
+  if (zoom) {
+    options.zoom = zoom;
+  }
+  return options;
+};
+export const queryFromStorage = () => {
+  return localStorage.getItem("query");
+};

package/lib/normalize.js

@@ -0,0 +1,5 @@
+import normalize from "normalize.css/normalize.css";
+import base from "./base.css";
+
+export const normalizeCSS = new CSSStyleSheet();
+normalizeCSS.replaceSync(normalize + base);

package/lib/queryMap.js

@@ -0,0 +1,50 @@
+import maplibregl from "maplibre-gl";
+
+import { h } from "../lib/dom.js";
+
+export const handleMouseMove = (e, popupTemplate, querySources) => {
+  if (popupTemplate === false) {
+    return;
+  }
+  const features = e.target
+    .queryRenderedFeatures(e.point)
+    .filter((l) => querySources?.includes(l.source));
+  if (features.length > 0) {
+    e.target.getCanvas().style.cursor = "pointer";
+  } else {
+    e.target.getCanvas().style.cursor = "";
+  }
+};
+
+export const handleMouseClick = (
+  e,
+  popupTemplate,
+  popupContextBuilder,
+  querySources,
+) => {
+  if (popupTemplate === false) {
+    return;
+  }
+  const features = e.target
+    .queryRenderedFeatures(e.point)
+    .filter((l) => querySources?.includes(l.source));
+  const distinctFeatures = {};
+  for (const f of features) {
+    distinctFeatures[f.id] = f;
+  }
+  const popup = h("map-popup");
+  popup.features = distinctFeatures;
+  if (popupTemplate) {
+    popup.template = popupTemplate;
+  }
+  if (popupContextBuilder) {
+    popup.contextBuilder = popupContextBuilder;
+  }
+  if (features.length > 0) {
+    new maplibregl.Popup()
+      .setMaxWidth("400px")
+      .setLngLat(e.lngLat)
+      .setDOMContent(popup)
+      .addTo(e.target);
+  }
+};