@fusion.dev/helix-map 0.114.0 → 0.115.0

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

@@ -0,0 +1,23 @@
+import type { MapPlace } from './connect-map.js';
+/** Where an area's caption stands, and which part of it stands there. */
+export interface CaptionSpot {
+    /** `center` on the spot, or `bottom`, the caption above the spot. */
+    anchor: 'bottom' | 'center';
+    at: MapPlace;
+}
+/**
+ * Where an area's caption stands.
+ *
+ * **Inside, at the point furthest from every edge**, where the most room is:
+ * the middle of the corners lies outside an L-shaped or a crescent area, and
+ * its caption read as the next area's. Found by laying a grid over the area,
+ * keeping the cell with the most room round it, and laying a finer grid over
+ * that, which is close enough for a caption and costs a few hundred
+ * measurements an area. Measured flat, the longitude narrowed by the
+ * latitude, so an area far from the equator is not judged wider than it is.
+ *
+ * **Outside, above its northernmost point**, clear of the shape, for an area
+ * whose caption would hide what is in it: the caption stands on the spot and
+ * reads above the edge.
+ */
+export declare const captionAt: (points: readonly MapPlace[], placement: 'inside' | 'outside') => CaptionSpot;

package/dist/connect-map/caption.js

@@ -0,0 +1,80 @@
+const CELLS = 16;
+const ROUNDS = 3;
+const inside = ({ x, y }, ring) => {
+    let crossed = false;
+    for (let at = 0, before = ring.length - 1; at < ring.length; before = at++) {
+        const a = ring[at];
+        const b = ring[before];
+        if (a.y > y !== b.y > y && x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x) {
+            crossed = !crossed;
+        }
+    }
+    return crossed;
+};
+const clearance = (point, ring) => {
+    let least = Number.POSITIVE_INFINITY;
+    for (let at = 0, before = ring.length - 1; at < ring.length; before = at++) {
+        const a = ring[before];
+        const b = ring[at];
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const length = dx * dx + dy * dy;
+        const along = length === 0
+            ? 0
+            : Math.min(Math.max(((point.x - a.x) * dx + (point.y - a.y) * dy) / length, 0), 1);
+        least = Math.min(least, Math.hypot(point.x - (a.x + along * dx), point.y - (a.y + along * dy)));
+    }
+    return least;
+};
+export const captionAt = (points, placement) => {
+    if (placement === 'outside') {
+        const north = Math.max(...points.map(({ lat }) => lat));
+        const top = points.filter(({ lat }) => north - lat < 1e-9);
+        const lng = top.reduce((sum, one) => sum + one.lng, 0) / top.length;
+        return { anchor: 'bottom', at: { lat: north, lng } };
+    }
+    const middle = points.reduce((sum, one) => sum + one.lat, 0) / points.length;
+    const narrow = Math.cos((middle * Math.PI) / 180) || 1;
+    const ring = points.map(({ lat, lng }) => ({ x: lng * narrow, y: lat }));
+    let west = Math.min(...ring.map(({ x }) => x));
+    let east = Math.max(...ring.map(({ x }) => x));
+    let south = Math.min(...ring.map(({ y }) => y));
+    let north = Math.max(...ring.map(({ y }) => y));
+    const center = { x: (west + east) / 2, y: (south + north) / 2 };
+    const offCenter = ({ x, y }) => Math.hypot(x - center.x, y - center.y);
+    const TIE = 0.02;
+    let best;
+    for (let round = 0; round < ROUNDS; round++) {
+        const width = (east - west) / CELLS;
+        const height = (north - south) / CELLS;
+        for (let column = 0; column < CELLS; column++) {
+            for (let row = 0; row < CELLS; row++) {
+                const point = { x: west + (column + 0.5) * width, y: south + (row + 0.5) * height };
+                if (!inside(point, ring)) {
+                    continue;
+                }
+                const room = clearance(point, ring);
+                const better = !best ||
+                    room > best.room * (1 + TIE) ||
+                    (room >= best.room * (1 - TIE) && offCenter(point) < offCenter(best.point));
+                if (better) {
+                    best = { point, room };
+                }
+            }
+        }
+        if (!best) {
+            break;
+        }
+        west = best.point.x - width;
+        east = best.point.x + width;
+        south = best.point.y - height;
+        north = best.point.y + height;
+    }
+    const at = best
+        ? { lat: best.point.y, lng: best.point.x / narrow }
+        : {
+            lat: middle,
+            lng: points.reduce((sum, one) => sum + one.lng, 0) / points.length,
+        };
+    return { anchor: 'center', at };
+};

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

@@ -192,6 +192,19 @@ export type MapPadding = number | {
 export interface MapLayerSpec {
     /** A raster layer's credit for its tiles, which the frame shows with the map's own. */
     attribution?: string | undefined;
+    /**
+     * An area's caption: its words, the place they stand on and which part of
+     * them stands there, `center` or `bottom` for words above the place, and
+     * the colors to draw them in, an `ink` that reads on the map and a `halo`
+     * of the land round it. Drawn above the place names, and never pressed.
+     */
+    caption?: {
+        anchor: 'bottom' | 'center';
+        at: MapPlace;
+        halo: string;
+        ink: string;
+        text: string;
+    } | undefined;
     /**
      * A route's edge, drawn wider under it so it reads as laid over the roads
      * rather than as one of them, where the roads are drawn in the same brand;

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

@@ -2,8 +2,10 @@ import { HelixActivateEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPar
 import { creditParts } from '../credit/credit.js';
 import { motionOf } from '../motion/motion.js';
 import { pointsFrom } from '../points/points.js';
-import { settledColor } from '../style/map-colors.js';
+import { colorsNow, settledColor } from '../style/map-colors.js';
+import { legible, parseColor } from '../style/oklab.js';
 import { watchTheme } from '../theme/watch-theme.js';
+import { captionAt } from './caption.js';
 const SAME_SPOT = 2;
 const fanOut = (count, spacing) => {
     if (count <= 8) {
@@ -48,6 +50,7 @@ const UNPLACED_POSITION = {
     '--_map-position-x': undefined,
     '--_map-position-y': undefined,
 };
+const CAPTION_CONTRAST = 4.5;
 const METERS_PER_DEGREE = 111_320;
 const LEAST_REACH = 0.005;
 export const reachOf = (places, least = 0) => {
@@ -389,6 +392,24 @@ export const connectMap = (frame, driver, options = {}) => {
         seen = next;
         place();
     };
+    let captionTheme;
+    const captionOf = (layer, text, color) => {
+        if (captionTheme === undefined) {
+            const colors = colorsNow(frame);
+            const land = colors ? parseColor(colors.surface) : undefined;
+            const ink = colors ? parseColor(colors.foreground) : undefined;
+            captionTheme = colors && land && ink ? { halo: colors.surface, ink, land } : null;
+        }
+        const own = parseColor(color);
+        return {
+            ...captionAt(layer.points ?? [], layer.captionPlacement ?? 'inside'),
+            halo: captionTheme?.halo ?? 'rgba(0, 0, 0, 0)',
+            ink: captionTheme && own
+                ? legible(own, captionTheme.ink, captionTheme.land, CAPTION_CONTRAST)
+                : color,
+            text,
+        };
+    };
     const readLayers = () => {
         pointLayers.clear();
         return readShown();
@@ -496,7 +517,9 @@ export const connectMap = (frame, driver, options = {}) => {
         }
         const edge = layer.layerKind === 'route' ? settledColor(layer, 'border-top-color') : color;
         const dotted = layer.layerKind === 'route' && layer.variant === 'dotted';
+        const words = layer.layerKind === 'area' ? layer.caption?.trim() : undefined;
         const spec = {
+            ...(words ? { caption: captionOf(layer, words, color) } : {}),
             ...(edge && edge !== color && !dotted ? { casing: edge } : {}),
             color,
             id: idOf(layer),
@@ -799,7 +822,12 @@ export const connectMap = (frame, driver, options = {}) => {
         soon({ draw: true, place: true });
     });
     children.observe(frame, { childList: true });
-    const stopTheming = drawn ? watchTheme(frame, () => drawn.update()) : undefined;
+    const stopTheming = drawn
+        ? watchTheme(frame, () => {
+            captionTheme = undefined;
+            drawn.update();
+        })
+        : undefined;
     place();
     const reveal = (event) => {
         const marker = event.composedPath().find(isMarker);

package/dist/leaflet/leaflet-driver.d.ts

@@ -86,6 +86,22 @@ export interface LeafletShapes {
     circleMarker?(latlng: [number, number], options: LeafletShapeOptions & {
         radius: number;
     }): LeafletShape;
+    /** An icon of the page's own markup, which an area's caption is drawn in. */
+    divIcon?(options: {
+        className: string;
+        html: HTMLElement;
+        iconSize: [number, number];
+    }): unknown;
+    /**
+     * A marker at a place, which an area's caption stands on. `icon` takes
+     * `never` for `addTo`'s reason: it is what `divIcon` made, which Leaflet
+     * types as its own class.
+     */
+    marker?(latlng: [number, number], options: {
+        icon: never;
+        interactive: boolean;
+        keyboard: boolean;
+    }): LeafletShape;
     polygon(latlngs: [number, number][], options: LeafletShapeOptions): LeafletShape;
     polyline(latlngs: [number, number][], options: LeafletShapeOptions): LeafletShape;
     /** A layer of map tiles from a URL, which a raster layer's frames are drawn in. */

package/dist/leaflet/leaflet-driver.js

@@ -77,6 +77,36 @@ export const leafletDriver = (map, shapes) => ({
                 let drawn = [];
                 const circles = new Map();
                 let placed = new Map();
+                const captionOf = (caption) => {
+                    if (!caption || !shapes.marker || !shapes.divIcon) {
+                        return [];
+                    }
+                    const words = document.createElement('span');
+                    words.textContent = caption.text;
+                    const halo = caption.halo;
+                    Object.assign(words.style, {
+                        color: caption.ink,
+                        font: '600 14px/1 var(--helix-font-sans, sans-serif)',
+                        left: '0',
+                        pointerEvents: 'none',
+                        position: 'absolute',
+                        textShadow: `0 0 2px ${halo}, 0 0 2px ${halo}, 0 0 3px ${halo}`,
+                        top: '0',
+                        transform: caption.anchor === 'bottom' ? 'translate(-50%, -130%)' : 'translate(-50%, -50%)',
+                        whiteSpace: 'nowrap',
+                    });
+                    return [
+                        shapes.marker([caption.at.lat, caption.at.lng], {
+                            icon: shapes.divIcon({
+                                className: 'helix-map-caption',
+                                html: words,
+                                iconSize: [0, 0],
+                            }),
+                            interactive: false,
+                            keyboard: false,
+                        }),
+                    ];
+                };
                 const rasters = new Map();
                 const drawRasters = (specs) => {
                     const make = shapes.tileLayer;
@@ -203,10 +233,11 @@ export const leafletDriver = (map, shapes) => ({
                                 interactive: false,
                                 weight: 1.5,
                             });
-                        for (const one of [...casing, shape]) {
+                        const caption = layer.kind === 'area' ? captionOf(layer.caption) : [];
+                        for (const one of [...casing, shape, ...caption]) {
                             one.addTo(map);
                         }
-                        return [...casing, shape];
+                        return [...casing, shape, ...caption];
                     });
                     for (const [id, had] of [...circles]) {
                         if (!kept.has(id)) {

package/dist/maplibre/maplibre-driver.d.ts

@@ -14,7 +14,7 @@ interface MapLibreEvent {
 }
 /** The frame's routes and areas, as MapLibre draws GeoJSON. */
 interface GeoJson {
-    features: {
+    features: ({
         geometry: {
             coordinates: unknown;
             type: 'LineString' | 'Polygon';
@@ -28,7 +28,20 @@ interface GeoJson {
             pattern?: 'dotted';
         };
         type: 'Feature';
-    }[];
+    } | {
+        geometry: {
+            coordinates: [number, number];
+            type: 'Point';
+        };
+        properties: {
+            anchor: 'bottom' | 'center';
+            halo: string;
+            ink: string;
+            kind: 'caption';
+            text: string;
+        };
+        type: 'Feature';
+    })[];
     type: 'FeatureCollection';
 }
 /**
@@ -51,6 +64,8 @@ type MapLibreLayer = {
 };
 /** Their layers, from the bottom up: areas under their own edges, routes over both. */
 export declare const LAYERS: MapLibreLayer[];
+/** The caption layer, in the face the style draws its names in. */
+export declare const captionLayer: (font: readonly string[]) => Record<string, unknown>;
 /** The routes and areas as GeoJSON, longitude first, an area's ring closed as GeoJSON requires. */
 export declare const geoJson: (layers: MapLayerSpec[]) => GeoJson;
 /**

package/dist/maplibre/maplibre-driver.js

@@ -58,13 +58,62 @@ export const LAYERS = [
         type: 'line',
     },
 ];
+const CAPTIONS = 'helix-area-captions';
+export const captionLayer = (font) => ({
+    filter: ['==', ['get', 'kind'], 'caption'],
+    id: CAPTIONS,
+    layout: {
+        'text-allow-overlap': true,
+        'text-anchor': ['get', 'anchor'],
+        'text-field': ['get', 'text'],
+        'text-font': font,
+        'text-offset': [
+            'case',
+            ['==', ['get', 'anchor'], 'bottom'],
+            ['literal', [0, -0.3]],
+            ['literal', [0, 0]],
+        ],
+        'text-size': 14,
+    },
+    paint: { 'text-color': ['get', 'ink'], 'text-halo-color': ['get', 'halo'], 'text-halo-width': 2 },
+    source: SOURCE,
+    type: 'symbol',
+});
+const faceOf = (map) => {
+    const faces = (map.getStyle()?.layers ?? [])
+        .filter((layer) => layer.type === 'symbol')
+        .map((layer) => layer.layout?.['text-font'])
+        .filter((face) => Array.isArray(face) &&
+        face.every((one) => typeof one === 'string') &&
+        !face.some((one) => /italic/i.test(one)));
+    return (faces.find((face) => face.some((one) => /medium|semibold|bold/i.test(one))) ??
+        faces[0] ?? ['Noto Sans Regular']);
+};
 export const geoJson = (layers) => ({
     features: layers.flatMap((layer) => {
         if (layer.kind !== 'area' && layer.kind !== 'route') {
             return [];
         }
         const coordinates = layer.points.map(({ lat, lng }) => [lng, lat]);
-        return {
+        const caption = layer.caption
+            ? [
+                {
+                    geometry: {
+                        coordinates: [layer.caption.at.lng, layer.caption.at.lat],
+                        type: 'Point',
+                    },
+                    properties: {
+                        anchor: layer.caption.anchor,
+                        halo: layer.caption.halo,
+                        ink: layer.caption.ink,
+                        kind: 'caption',
+                        text: layer.caption.text,
+                    },
+                    type: 'Feature',
+                },
+            ]
+            : [];
+        const shape = {
             geometry: layer.kind === 'route'
                 ? { coordinates, type: 'LineString' }
                 : { coordinates: [[...coordinates, coordinates[0]]], type: 'Polygon' },
@@ -78,6 +127,7 @@ export const geoJson = (layers) => ({
             },
             type: 'Feature',
         };
+        return [shape, ...caption];
     }),
     type: 'FeatureCollection',
 });
@@ -798,6 +848,7 @@ export const mapLibreDriver = (map) => ({
             for (const layer of LAYERS) {
                 map.addLayer(layer, labels);
             }
+            map.addLayer(captionLayer(faceOf(map)));
             drawExtras(specs.filter((spec) => EXTRAS.has(spec.kind)));
         };
         const restore = () => {
@@ -950,9 +1001,9 @@ export const mapLibreDriver = (map) => ({
                 for (const id of [...drawnExtras.keys()]) {
                     takeOffExtra(id);
                 }
-                for (const layer of [...LAYERS].reverse()) {
-                    if (map.getLayer(layer.id)) {
-                        map.removeLayer(layer.id);
+                for (const id of [CAPTIONS, ...[...LAYERS].reverse().map((layer) => layer.id)]) {
+                    if (map.getLayer(id)) {
+                        map.removeLayer(id);
                     }
                 }
                 if (map.getSource(SOURCE)) {

package/dist/style/map-style.js

@@ -1,5 +1,5 @@
 import { bed, firstAid, forkKnife, graduationCap, shoppingBag, star, train, tree, trophy, } from '@fusion.dev/helix-icons';
-import { contrast, cssColor, mix, parseColor, rehue } from './oklab.js';
+import { cssColor, legible as legibleOn, mix, parseColor, rehue } from './oklab.js';
 const OPENFREEMAP = {
     glyphs: 'https://tiles.openfreemap.org/fonts/{fontstack}/{range}.pbf',
     tiles: 'https://tiles.openfreemap.org/planet',
@@ -112,27 +112,7 @@ export const mapLibreStyle = (colors, options = {}) => {
     const BOLD = face ? [`${face} Bold`, face] : ['Noto Sans Bold'];
     const ITALIC = face ? [`${face} Italic`, face] : ['Noto Sans Italic'];
     const glyphs = face ? options.glyphs : (options.glyphs ?? OPENFREEMAP.glyphs);
-    const legible = (from, amount) => {
-        const at = (step) => parseColor(cssColor(mix(from, ink, step)));
-        if (contrast(at(amount), land) >= target) {
-            return cssColor(at(amount));
-        }
-        if (contrast(ink, land) < target) {
-            return cssColor(ink);
-        }
-        let low = amount;
-        let high = 1;
-        for (let round = 0; round < 20; round++) {
-            const middle = (low + high) / 2;
-            if (contrast(at(middle), land) >= target) {
-                high = middle;
-            }
-            else {
-                low = middle;
-            }
-        }
-        return cssColor(at(high));
-    };
+    const legible = (from, amount) => legibleOn(from, ink, land, target, amount);
     const road = (id, classes, color, width, minzoom) => ({
         filter: ['all', lines, notTunnel, ['match', ['get', 'class'], classes, true, false]],
         id,

package/dist/style/oklab.d.ts

@@ -33,3 +33,13 @@ export declare const oklch: (lightness: number, chroma: number, hue: number) =>
 export declare const cssColor: ({ alpha, blue, green, red }: Rgb) => string;
 /** The WCAG contrast ratio between two colors, from 1 to 21. */
 export declare const contrast: (one: Rgb, other: Rgb) => number;
+/**
+ * A color that can be read on a ground: `from` mixed toward `ink` by
+ * `amount`, and further until it clears `target` against `ground`, or `ink`
+ * itself where nothing short of it does. What the style draws its labels in,
+ * and an area's caption.
+ *
+ * **Measured as it will be drawn**, rounded to eight bits a channel: the
+ * unrounded color cleared 7:1 and the one written out read 6.96.
+ */
+export declare const legible: (from: Rgb, ink: Rgb, ground: Rgb, target: number, amount?: number) => string;

package/dist/style/oklab.js

@@ -73,3 +73,24 @@ export const contrast = (one, other) => {
     const [light, dark] = [luminance(one), luminance(other)].sort((a, b) => b - a);
     return (light + 0.05) / (dark + 0.05);
 };
+export const legible = (from, ink, ground, target, amount = 0) => {
+    const at = (step) => parseColor(cssColor(mix(from, ink, step)));
+    if (contrast(at(amount), ground) >= target) {
+        return cssColor(at(amount));
+    }
+    if (contrast(ink, ground) < target) {
+        return cssColor(ink);
+    }
+    let low = amount;
+    let high = 1;
+    for (let round = 0; round < 20; round++) {
+        const middle = (low + high) / 2;
+        if (contrast(at(middle), ground) >= target) {
+            high = middle;
+        }
+        else {
+            low = middle;
+        }
+    }
+    return cssColor(at(high));
+};

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.114.0",
+  "version": "0.115.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -43,14 +43,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.114.0",
-    "@fusion.dev/helix-icons": "0.114.0",
+    "@fusion.dev/helix-core": "0.115.0",
+    "@fusion.dev/helix-icons": "0.115.0",
     "@mapbox/vector-tile": "^3.0.0",
     "pbf": "^5.1.2"
   },
   "devDependencies": {
-    "@fusion.dev/helix-headless": "0.114.0",
-    "@fusion.dev/helix-testing": "0.114.0",
+    "@fusion.dev/helix-headless": "0.115.0",
+    "@fusion.dev/helix-testing": "0.115.0",
     "@maplibre/maplibre-gl-style-spec": "^26.4.4",
     "@types/bun": "^1.3.0",
     "@types/leaflet": "^1.9.20",