@fusion.dev/helix-map 0.205.2 → 0.207.0

package/README.md

@@ -14,8 +14,14 @@ for the first paint, the keyboard, and writing a driver. The elements themselves
 [Map reference](https://fusion.dev/helix/components/map).
 
 ```js
+import '@fusion.dev/helix/map'
+import 'maplibre-gl/dist/maplibre-gl.css'
 import { colorsReady, connectMap } from '@fusion.dev/helix-map'
 import { followTheme, mapLibreDriver, mapLibreStyle } from '@fusion.dev/helix-map/maplibre'
+import * as maplibregl from 'maplibre-gl'
+
+// MapLibre 6 runs its worker from a file of its own. Point it there once.
+maplibregl.setWorkerUrl('/maplibre/maplibre-gl-worker.mjs')
 
 const frame = document.querySelector('helix-map')
 const style = (colors) => mapLibreStyle(colors)
@@ -26,19 +32,31 @@ const map = new maplibregl.Map({
 })
 
 const connection = connectMap(frame, mapLibreDriver(map))
+connection.fit({ animate: false })
 followTheme(map, frame, style)
 
 // Later, when the map goes away:
 connection.disconnect()
 ```
 
+MapLibre 6 runs its worker from two files, `maplibre-gl-worker.mjs` and
+`maplibre-gl-shared.mjs`. Serve both from one folder, and pass the worker's
+address to `setWorkerUrl` before you create a map, as the guide shows.
+
+**The map's tiles come from OpenFreeMap by default**, and so do its glyphs
+where you pass no `font`. OpenFreeMap needs no key. The requests go to its
+servers: from your reader's browser for the map, and from your server for
+`mapSnapshot`. Pass `tiles` and `glyphs` to `mapLibreStyle`, and `tiles` to
+`mapSnapshot`, to use your own servers.
+
 ## What it exports
 
 | Import | What |
 |---|---|
-| `@fusion.dev/helix-map` | `connectMap`, `colorsReady`, `mapColorsFrom`, `watchTheme`, `motionOf`, `distancesAlong`, `pointsFrom`, and the `MapDriver` type |
+| `@fusion.dev/helix-map` | `connectMap`, `colorsReady`, `mapColorsFrom`, `mapFontFrom`, `fontReady`, `watchTheme`, `motionOf`, `distancesAlong`, `pointsFrom`, and the `MapDriver` type |
 | `@fusion.dev/helix-map/maplibre` | `mapLibreDriver(map)`, `mapLibreStyle(colors, options)`, `followTheme(map, element, style)` |
 | `@fusion.dev/helix-map/leaflet` | `leafletDriver(map, L)` |
+| `@fusion.dev/helix-map/snapshot` | `mapSnapshot(view, options)`, an SVG of the map drawn on your server to paint before the renderer loads, with the credit its tiles name |
 
 **Neither renderer is a dependency.** A driver types the map it takes by the
 calls it makes on it, so a page brings whichever version it has. A spec holds

package/dist/connect-map/connect-map.d.ts

@@ -312,7 +312,9 @@ export declare const distancesAlong: (points: readonly MapPlace[]) => number[];
 export interface ConnectOptions {
     /**
      * Whether the renderer's credit fills the frame's `attribution` slot. On by
-     * default, and left alone either way where the page slotted its own.
+     * default, and left alone either way where the page slotted its own. A
+     * snapshot's credit stays until the renderer's is written, and stays for
+     * good with `false`.
      */
     credit?: boolean | undefined;
     /**
@@ -361,7 +363,8 @@ export interface MapConnection {
  * the frame draws its own; the frame's markers stood on their places as the
  * view moves, and brought into view as the keyboard reaches them; and the
  * renderer's credit written into the frame's
- * `attribution` slot as text and links, kept current as its sources change.
+ * `attribution` slot as text and links, kept current as its sources change,
+ * in place of a snapshot's.
  *
  * The frame is `helix-map` or `helix-headless-map`, and the driver is
  * `mapLibreDriver`, `leafletDriver` or one of the page's own.

package/dist/connect-map/connect-map.js

@@ -1,5 +1,5 @@
 import { HelixActivateEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
-import { creditParts } from '../credit/credit.js';
+import { CREDIT, creditParts } from '../credit/credit.js';
 import { motionOf } from '../motion/motion.js';
 import { pointsFrom } from '../points/points.js';
 import { colorsNow, settledColor } from '../style/map-colors.js';
@@ -142,7 +142,6 @@ const idOf = (element) => {
     }
     return id;
 };
-const CREDIT = 'data-helix-map-credit';
 const viewportOf = (frame) => {
     const box = (frame.shadowRoot?.querySelector('[part="viewport"]') ?? frame).getBoundingClientRect();
     return { height: box.height, width: box.width };
@@ -258,6 +257,18 @@ export const connectMap = (frame, driver, options = {}) => {
     const tabindex = focusable?.getAttribute('tabindex') ?? null;
     focusable?.setAttribute('tabindex', '-1');
     const owned = [...frame.children].some((child) => child.getAttribute('slot') === 'attribution' && !child.hasAttribute(CREDIT));
+    const served = [...frame.children].filter((child) => child instanceof HTMLElement &&
+        child.getAttribute('slot') === 'attribution' &&
+        child.hasAttribute(CREDIT));
+    const stepAside = () => {
+        for (const one of served) {
+            one.hidden = true;
+            one.style.display = 'none';
+        }
+    };
+    if (owned) {
+        stepAside();
+    }
     let credit;
     let listening;
     let written;
@@ -300,8 +311,11 @@ export const connectMap = (frame, driver, options = {}) => {
         if (nodes.length === 0) {
             credit.remove();
         }
-        else if (credit.parentNode !== frame) {
-            frame.append(credit);
+        else {
+            stepAside();
+            if (credit.parentNode !== frame) {
+                frame.append(credit);
+            }
         }
     };
     if (options.credit !== false && !owned && driver.credits) {

package/dist/credit/credit.d.ts

@@ -5,6 +5,18 @@ export interface CreditPart {
     /** The words, as they are read. */
     text: string;
 }
+/**
+ * What marks a credit Helix wrote, the connector's or a snapshot's, so the
+ * connector can tell one from the page's own: it replaces a credit with this,
+ * and leaves one without it alone.
+ */
+export declare const CREDIT = "data-helix-map-credit";
+/**
+ * A credit as the markup the connector writes into the frame: a span in the
+ * `attribution` slot, marked as Helix's, of words and links that open in a new
+ * tab in the text's own color. Nothing where the credit says nothing.
+ */
+export declare const creditMarkup: (parts: readonly CreditPart[]) => string;
 /**
  * A renderer's credits as runs of text and links, and nothing else.
  *
@@ -14,6 +26,8 @@ export interface CreditPart {
  * in the page this sits in. So every element but a link is taken for its
  * words, a link only where it leads to `http` or `https`, and the result is
  * written with `textContent`. Two credits that read the same are one, which
- * is what a style that names OpenStreetMap on every source needs.
+ * is what a style that names OpenStreetMap on every source needs. A server,
+ * which has no `DOMParser`, reads the same runs from the markup, so the credit
+ * `mapSnapshot` writes reads as the one the renderer gives later.
  */
 export declare const creditParts: (credits: readonly string[]) => CreditPart[];

package/dist/credit/credit.js

@@ -1,4 +1,5 @@
 const BETWEEN = ' | ';
+export const CREDIT = 'data-helix-map-credit';
 const safe = (href) => {
     if (!href) {
         return false;
@@ -28,6 +29,70 @@ const walk = (node, into) => {
         }
     }
 };
+const ENTITIES = {
+    amp: '&',
+    apos: "'",
+    copy: '©',
+    gt: '>',
+    lt: '<',
+    nbsp: '\u00a0',
+    quot: '"',
+    reg: '®',
+};
+const decoded = (words) => words.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (written, name) => {
+    if (name.startsWith('#')) {
+        const code = /x/i.test(name) ? Number.parseInt(name.slice(2), 16) : Number(name.slice(1));
+        return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : written;
+    }
+    return ENTITIES[name.toLowerCase()] ?? written;
+});
+const TAG = /<!--[\s\S]*?-->|<(\/?)([a-z][^\s/>]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/gi;
+const HREF = /\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/i;
+const read = (markup, into) => {
+    let link;
+    let from = 0;
+    const words = (written) => {
+        if (written === '') {
+            return;
+        }
+        if (link) {
+            link.text += decoded(written);
+        }
+        else {
+            into.push({ text: decoded(written) });
+        }
+    };
+    for (const tag of markup.matchAll(TAG)) {
+        words(markup.slice(from, tag.index));
+        from = tag.index + tag[0].length;
+        if (tag[2]?.toLowerCase() !== 'a') {
+            continue;
+        }
+        if (tag[1] === '/') {
+            if (link) {
+                into.push(link);
+            }
+            link = undefined;
+        }
+        else if (!link) {
+            const found = HREF.exec(tag[3] ?? '');
+            const href = found ? decoded(found[1] ?? found[2] ?? found[3] ?? '') : null;
+            link = safe(href) ? { href, text: '' } : undefined;
+        }
+    }
+    words(markup.slice(from));
+    if (link) {
+        into.push(link);
+    }
+};
+const escaped = (words) => words.replace(/[&<>"]/g, (character) => `&#${character.charCodeAt(0)};`);
+export const creditMarkup = (parts) => parts.length === 0
+    ? ''
+    : `<span ${CREDIT} slot="attribution">${parts
+        .map((part) => part.href === undefined
+        ? escaped(part.text)
+        : `<a data-link="quiet" href="${escaped(part.href)}" rel="noopener noreferrer" target="_blank">${escaped(part.text)}</a>`)
+        .join('')}</span>`;
 export const creditParts = (credits) => {
     const seen = new Set();
     const parts = [];
@@ -37,7 +102,7 @@ export const creditParts = (credits) => {
             walk(new DOMParser().parseFromString(credit, 'text/html').body, runs);
         }
         else {
-            runs.push({ text: credit.replace(/<[^>]*>/g, '') });
+            read(credit, runs);
         }
         const clean = runs
             .map((run) => ({ ...run, text: run.text.replace(/\s+/g, ' ') }))

package/dist/snapshot/index.d.ts

@@ -1,4 +1,5 @@
+export type { CreditPart } from '../credit/credit.js';
 export type { MapCamera, MapView, ScreenPoint } from './camera.js';
 export { cameraOf, worldOf } from './camera.js';
-export type { SnapshotLayer, SnapshotOptions, SnapshotToward } from './snapshot.js';
+export type { MapSnapshot, SnapshotLayer, SnapshotOptions, SnapshotToward } from './snapshot.js';
 export { mapSnapshot, SNAPSHOT_LAYERS, widthAt } from './snapshot.js';

package/dist/snapshot/snapshot.d.ts

@@ -1,3 +1,4 @@
+import { type CreditPart } from '../credit/credit.js';
 import { type MapView } from './camera.js';
 /** The token a snapshot layer's color is the land moved toward. */
 export type SnapshotToward = 'foreground' | 'info' | 'primary' | 'success';
@@ -52,6 +53,24 @@ export interface SnapshotOptions {
     /** A TileJSON URL for vector tiles in the OpenMapTiles schema: the one given to `mapLibreStyle`. OpenFreeMap's by default. */
     tiles?: string | undefined;
 }
+/** A map drawn on the server, and the credit its tiles ask for. */
+export interface MapSnapshot {
+    /**
+     * The tiles' credit, read from their TileJSON's `attribution`, as runs of
+     * words and links: for a framework that writes `picture` in an element of
+     * its own, and the credit in a `<span slot="attribution">` with
+     * `data-helix-map-credit`. Empty where the tiles name none.
+     */
+    credit: CreditPart[];
+    /**
+     * The picture, then the credit in the frame's `attribution` slot, as markup
+     * to write in the frame after the element the renderer draws in. An empty
+     * string where the snapshot could not be drawn.
+     */
+    markup: string;
+    /** The picture alone, as markup. An empty string where it could not be drawn. */
+    picture: string;
+}
 /**
  * **A map drawn on the server, for the page's first paint**: an SVG of the
  * view a renderer is about to draw, from the same vector tiles and in the
@@ -70,11 +89,19 @@ export interface SnapshotOptions {
  * toward a token in OKLab, so it is drawn in whichever theme the page is in,
  * light or dark, and changes with it.
  *
- * **Whole or nothing.** Resolves to an empty string where any tile the view
- * needs cannot be read in time, or the view is not numbers, which a page
- * renders as nothing and the renderer then draws. A snapshot with a tile
- * missing looks finished and is not, and one that waited on a slow server
- * held the page: each request is given `timeout` milliseconds. A tile the
- * server says it does not have, a 404, is drawn empty, as the sea is.
+ * **Credited from the first paint.** Most tile licenses require the credit
+ * wherever the map is shown, and a frame showing the snapshot while the
+ * renderer loads, or a page that never loads one, has no renderer's credit.
+ * So the snapshot carries the credit the tiles' TileJSON names, and `markup`
+ * writes it in the frame's `attribution` slot, marked as Helix's:
+ * `connectMap` hides it once the renderer's credit is written, or at once
+ * where the page slotted its own.
+ *
+ * **Whole or nothing.** Holds empty strings where any tile the view needs
+ * cannot be read in time, or the view is not numbers, which a page renders
+ * as nothing and the renderer then draws. A snapshot with a tile missing
+ * looks finished and is not, and one that waited on a slow server held the
+ * page: each request is given `timeout` milliseconds. A tile the server says
+ * it does not have, a 404, is drawn empty, as the sea is.
  */
-export declare const mapSnapshot: (asked: MapView, options?: SnapshotOptions) => Promise<string>;
+export declare const mapSnapshot: (asked: MapView, options?: SnapshotOptions) => Promise<MapSnapshot>;

package/dist/snapshot/snapshot.js

@@ -1,5 +1,6 @@
 import { VectorTile } from '@mapbox/vector-tile';
 import { PbfReader } from 'pbf';
+import { creditMarkup, creditParts } from '../credit/credit.js';
 import { cameraOf } from './camera.js';
 export const SNAPSHOT_LAYERS = [
     {
@@ -149,6 +150,7 @@ const simplified = (points) => {
     }
     return points.filter((_, index) => kept[index] === 1);
 };
+const nothing = () => ({ credit: [], markup: '', picture: '' });
 const OPENFREEMAP = 'https://tiles.openfreemap.org/planet';
 const MOST_TILES = 40;
 const MARGIN = 16;
@@ -163,7 +165,7 @@ export const mapSnapshot = async (asked, options = {}) => {
     };
     if (![view.bearing, view.center.lat, view.center.lng, view.pitch, view.zoom].every(Number.isFinite) ||
         !(view.width > 0 && view.height > 0)) {
-        return '';
+        return nothing();
     }
     const wait = options.timeout ?? 3000;
     const get = (url) => {
@@ -184,8 +186,10 @@ export const mapSnapshot = async (asked, options = {}) => {
         .catch(() => undefined);
     const template = tiles?.tiles?.[0];
     if (!template) {
-        return '';
+        return nothing();
     }
+    const attribution = tiles.attribution;
+    const credit = typeof attribution === 'string' ? creditParts([attribution]) : [];
     const deepest = tiles.maxzoom ?? 14;
     const camera = cameraOf(view);
     const corners = [
@@ -308,7 +312,7 @@ export const mapSnapshot = async (asked, options = {}) => {
         }
     }
     if (!whole) {
-        return '';
+        return nothing();
     }
     const body = shown
         .map((layer) => {
@@ -326,7 +330,8 @@ export const mapSnapshot = async (asked, options = {}) => {
             ], view.zoom).toFixed(2)}px;stroke-linecap:round;stroke-linejoin:round" d="${paths.join('')}"/>`;
     })
         .join('');
-    return (`<div aria-hidden="true" data-helix-map-snapshot style="inset:0;overflow:hidden;pointer-events:none;position:absolute">` +
+    const picture = `<div aria-hidden="true" data-helix-map-snapshot style="inset:0;overflow:hidden;pointer-events:none;position:absolute">` +
         `<svg height="${view.height}" viewBox="0 0 ${view.width} ${view.height}" width="${view.width}" xmlns="http://www.w3.org/2000/svg" style="background:var(${TOKENS.surface});left:50%;position:absolute;top:50%;translate:-50% -50%">` +
-        `${body}</svg></div>`);
+        `${body}</svg></div>`;
+    return { credit, markup: picture + creditMarkup(credit), picture };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-map",
   "description": "Connects the Helix Map frame to a map renderer: MapLibre, Leaflet, or a driver of your own.",
-  "version": "0.205.2",
+  "version": "0.207.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -25,6 +25,7 @@
       "types": "./dist/maplibre/index.d.ts",
       "default": "./dist/maplibre/index.js"
     },
+    "./package.json": "./package.json",
     "./snapshot": {
       "types": "./dist/snapshot/index.d.ts",
       "default": "./dist/snapshot/index.js"
@@ -43,14 +44,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.205.2",
-    "@fusion.dev/helix-icons": "0.205.2",
+    "@fusion.dev/helix-core": "0.207.0",
+    "@fusion.dev/helix-icons": "0.207.0",
     "@mapbox/vector-tile": "^3.0.0",
     "pbf": "^5.1.2"
   },
   "devDependencies": {
-    "@fusion.dev/helix-headless": "0.205.2",
-    "@fusion.dev/helix-testing": "0.205.2",
+    "@fusion.dev/helix-headless": "0.207.0",
+    "@fusion.dev/helix-testing": "0.207.0",
     "@maplibre/maplibre-gl-style-spec": "^26.4.4",
     "@types/bun": "^1.4.2",
     "@types/leaflet": "^1.9.20",