@loidolt/theme-maps 0.7.0

package/dist/core/bounds.js

@@ -0,0 +1,91 @@
+/** Whether a pair is a real longitude/latitude: finite, within ±180 and ±90. */
+export function isLngLat(value) {
+    return (Array.isArray(value) &&
+        value.length >= 2 &&
+        Number.isFinite(value[0]) &&
+        Number.isFinite(value[1]) &&
+        Math.abs(value[0]) <= 180 &&
+        Math.abs(value[1]) <= 90);
+}
+function* positions(geometry) {
+    if (!geometry)
+        return;
+    switch (geometry.type) {
+        case 'Point':
+            yield geometry.coordinates;
+            break;
+        case 'MultiPoint':
+        case 'LineString':
+            yield* geometry.coordinates;
+            break;
+        case 'MultiLineString':
+        case 'Polygon':
+            for (const ring of geometry.coordinates)
+                yield* ring;
+            break;
+        case 'MultiPolygon':
+            for (const polygon of geometry.coordinates)
+                for (const ring of polygon)
+                    yield* ring;
+            break;
+        case 'GeometryCollection':
+            for (const part of geometry.geometries)
+                yield* positions(part);
+            break;
+    }
+}
+/** Every coordinate in any GeoJSON object. */
+export function* coordinatesOf(data) {
+    if (data.type === 'FeatureCollection') {
+        for (const feature of data.features)
+            yield* positions(feature.geometry);
+    }
+    else if (data.type === 'Feature') {
+        yield* positions(data.geometry);
+    }
+    else {
+        yield* positions(data);
+    }
+}
+/**
+ * The box around GeoJSON or a list of points, or `null` when there is nothing to box. Does
+ * not handle data that crosses the antimeridian.
+ */
+export function boundsOf(data) {
+    let [west, south, east, north] = [Infinity, Infinity, -Infinity, -Infinity];
+    const points = Array.isArray(data) ? data : coordinatesOf(data);
+    for (const [lng, lat] of points) {
+        if (!Number.isFinite(lng) || !Number.isFinite(lat))
+            continue;
+        west = Math.min(west, lng);
+        east = Math.max(east, lng);
+        south = Math.min(south, lat);
+        north = Math.max(north, lat);
+    }
+    return Number.isFinite(west)
+        ? [
+            [west, south],
+            [east, north],
+        ]
+        : null;
+}
+/** The middle of a box. */
+export function boundsCenter([[west, south], [east, north]]) {
+    return [(west + east) / 2, (south + north) / 2];
+}
+/** Grows a box by a fraction of its size on every side (`0.1` adds 10%). */
+export function padBounds([[west, south], [east, north]], ratio) {
+    const [dx, dy] = [(east - west) * ratio, (north - south) * ratio];
+    return [
+        [Math.max(-180, west - dx), Math.max(-90, south - dy)],
+        [Math.min(180, east + dx), Math.min(90, north + dy)],
+    ];
+}
+/** Whether a point lies in a box, edges included. */
+export function boundsContain([[west, south], [east, north]], [lng, lat]) {
+    return lng >= west && lng <= east && lat >= south && lat <= north;
+}
+/** Whether two boxes overlap. */
+export function boundsIntersect(a, b) {
+    return a[0][0] <= b[1][0] && a[1][0] >= b[0][0] && a[0][1] <= b[1][1] && a[1][1] >= b[0][1];
+}

package/dist/core/cluster.d.ts

@@ -0,0 +1,35 @@
+import { type MapColors } from '@loidolt/theme-tokens';
+import type { LngLat } from './types.js';
+/**
+ * Cluster colour by size, stepping through the sequential ramp at the given point counts: the
+ * more points, the further along the ramp.
+ */
+export declare function clusterColor(colors?: Pick<MapColors, 'sequential'>, steps?: number[]): unknown[];
+/** Cluster radius by size, in pixels, at the same point counts. */
+export declare function clusterRadius(steps?: number[], radii?: number[]): unknown[];
+/** Whether a rendered feature is a cluster rather than one point. */
+export declare const isCluster: (feature: {
+    properties?: Record<string, unknown> | null;
+}) => boolean;
+interface ClusterMap {
+    getSource(id: string): unknown;
+    easeTo(options: {
+        center: LngLat;
+        zoom: number;
+        duration?: number;
+    }): void;
+}
+/**
+ * Zooms to where a clicked cluster splits apart. `animate: false` for reduced motion.
+ * Resolves `false` when the feature is not a cluster or its source cannot expand it.
+ */
+export declare function expandCluster(map: ClusterMap, sourceId: string, feature: {
+    properties?: Record<string, unknown> | null;
+    geometry?: {
+        type: string;
+        coordinates?: unknown;
+    } | null;
+}, { animate }?: {
+    animate?: boolean;
+}): Promise<boolean>;
+export {};

package/dist/core/cluster.js

@@ -0,0 +1,44 @@
+import { mapColors } from '@loidolt/theme-tokens';
+/*
+ * Clustering is a GeoJSON source option (`cluster` on `MapSource`). These build the paint for
+ * the cluster circles and handle the one interaction every cluster needs: click to zoom in.
+ */
+/**
+ * Cluster colour by size, stepping through the sequential ramp at the given point counts: the
+ * more points, the further along the ramp.
+ */
+export function clusterColor(colors = mapColors(), steps = [10, 50, 200]) {
+    const ramp = colors.sequential.slice(-(steps.length + 1));
+    return [
+        'step',
+        ['get', 'point_count'],
+        ramp[0],
+        ...steps.flatMap((step, index) => [step, ramp[index + 1] ?? ramp.at(-1)]),
+    ];
+}
+/** Cluster radius by size, in pixels, at the same point counts. */
+export function clusterRadius(steps = [10, 50, 200], radii = [14, 18, 24, 30]) {
+    return [
+        'step',
+        ['get', 'point_count'],
+        radii[0],
+        ...steps.flatMap((step, index) => [step, radii[index + 1] ?? radii.at(-1)]),
+    ];
+}
+/** Whether a rendered feature is a cluster rather than one point. */
+export const isCluster = (feature) => feature.properties?.cluster === true && typeof feature.properties.cluster_id === 'number';
+/**
+ * Zooms to where a clicked cluster splits apart. `animate: false` for reduced motion.
+ * Resolves `false` when the feature is not a cluster or its source cannot expand it.
+ */
+export async function expandCluster(map, sourceId, feature, { animate = true } = {}) {
+    const source = map.getSource(sourceId);
+    if (!isCluster(feature) || typeof source?.getClusterExpansionZoom !== 'function')
+        return false;
+    if (feature.geometry?.type !== 'Point')
+        return false;
+    const zoom = await source.getClusterExpansionZoom(feature.properties.cluster_id);
+    const [lng, lat] = feature.geometry.coordinates;
+    map.easeTo({ center: [lng, lat], zoom, duration: animate ? undefined : 0 });
+    return true;
+}

package/dist/core/data.d.ts

@@ -0,0 +1,33 @@
+import type { Feature, FeatureCollection, GeoJSON, LngLat } from './types.js';
+export interface GeoJSONCheck {
+    valid: boolean;
+    /** What is wrong, one message per problem, with a path such as `features[3].geometry`. */
+    errors: string[];
+}
+/**
+ * Checks that a value is GeoJSON a map can draw: known types, and positions that are real
+ * `[longitude, latitude]` pairs. The most common mistake it catches is `[lat, lng]` order,
+ * which puts a latitude above 90 in the longitude slot.
+ */
+export declare function validateGeoJSON(value: unknown): GeoJSONCheck;
+export interface LoadOptions {
+    signal?: AbortSignal;
+    /** Give up after this many milliseconds. */
+    timeout?: number;
+    /** For tests and custom transports. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** Fetches and validates GeoJSON. Rejects with a readable message when either fails. */
+export declare function loadGeoJSON(url: string, options?: LoadOptions): Promise<GeoJSON>;
+/** Points as a FeatureCollection, each keeping its own properties. */
+export declare function pointsToFeatureCollection<P extends Record<string, unknown>>(points: Array<{
+    lngLat: LngLat;
+    id?: string | number;
+    properties?: P;
+}>): FeatureCollection<P>;
+/**
+ * A representative point for a feature: the point itself, a line's middle vertex, or the
+ * average of a shape's outer ring. Good enough to fly to or to pin a label on; not a true
+ * centroid for concave shapes.
+ */
+export declare function featureAnchor(feature: Feature): LngLat | null;

package/dist/core/data.js

@@ -0,0 +1,157 @@
+import { isLngLat } from './bounds.js';
+const GEOMETRY_TYPES = new Set([
+    'Point',
+    'MultiPoint',
+    'LineString',
+    'MultiLineString',
+    'Polygon',
+    'MultiPolygon',
+    'GeometryCollection',
+]);
+function checkGeometry(value, path, errors) {
+    if (value === null)
+        return;
+    const geometry = value;
+    if (typeof value !== 'object' || !GEOMETRY_TYPES.has(geometry.type)) {
+        errors.push(`${path}: not a GeoJSON geometry`);
+        return;
+    }
+    if (geometry.type === 'GeometryCollection') {
+        if (!Array.isArray(geometry.geometries))
+            errors.push(`${path}.geometries: must be an array`);
+        else
+            geometry.geometries.forEach((part, index) => checkGeometry(part, `${path}.geometries[${index}]`, errors));
+        return;
+    }
+    const depth = {
+        Point: 0,
+        MultiPoint: 1,
+        LineString: 1,
+        MultiLineString: 2,
+        Polygon: 2,
+        MultiPolygon: 3,
+    }[geometry.type];
+    const walk = (node, level, where) => {
+        if (level === 0) {
+            if (!isLngLat(node))
+                errors.push(`${where}: not a [longitude, latitude] position`);
+            return;
+        }
+        if (!Array.isArray(node)) {
+            errors.push(`${where}: must be an array`);
+            return;
+        }
+        node.forEach((child, index) => walk(child, level - 1, `${where}[${index}]`));
+    };
+    walk(geometry.coordinates, depth, `${path}.coordinates`);
+}
+/**
+ * Checks that a value is GeoJSON a map can draw: known types, and positions that are real
+ * `[longitude, latitude]` pairs. The most common mistake it catches is `[lat, lng]` order,
+ * which puts a latitude above 90 in the longitude slot.
+ */
+export function validateGeoJSON(value) {
+    const errors = [];
+    const data = value;
+    if (typeof value !== 'object' || value === null) {
+        errors.push('not an object');
+    }
+    else if (data.type === 'FeatureCollection') {
+        if (!Array.isArray(data.features))
+            errors.push('features: must be an array');
+        else
+            data.features.forEach((feature, index) => {
+                if (feature?.type !== 'Feature')
+                    errors.push(`features[${index}]: not a Feature`);
+                else
+                    checkGeometry(feature.geometry, `features[${index}].geometry`, errors);
+            });
+    }
+    else if (data.type === 'Feature') {
+        checkGeometry(data.geometry, 'geometry', errors);
+    }
+    else {
+        checkGeometry(value, 'geometry', errors);
+    }
+    return { valid: errors.length === 0, errors };
+}
+/** Fetches and validates GeoJSON. Rejects with a readable message when either fails. */
+export async function loadGeoJSON(url, options = {}) {
+    const { timeout = 30_000, fetch: request = globalThis.fetch } = options;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, timeout);
+    try {
+        const response = await request(url, { signal: controller.signal });
+        if (!response.ok)
+            throw new Error(`loadGeoJSON: ${url} answered ${response.status}`);
+        const data = await response.json();
+        const check = validateGeoJSON(data);
+        if (!check.valid)
+            throw new Error(`loadGeoJSON: ${url} is not valid GeoJSON (${check.errors[0]})`);
+        return data;
+    }
+    catch (error) {
+        if (controller.signal.aborted && !options.signal?.aborted) {
+            throw new Error(`loadGeoJSON: ${url} took longer than ${timeout} ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+    }
+}
+/** Points as a FeatureCollection, each keeping its own properties. */
+export function pointsToFeatureCollection(points) {
+    return {
+        type: 'FeatureCollection',
+        features: points.map(({ lngLat, id, properties }) => ({
+            type: 'Feature',
+            ...(id === undefined ? {} : { id }),
+            geometry: { type: 'Point', coordinates: lngLat },
+            properties: properties ?? {},
+        })),
+    };
+}
+/**
+ * A representative point for a feature: the point itself, a line's middle vertex, or the
+ * average of a shape's outer ring. Good enough to fly to or to pin a label on; not a true
+ * centroid for concave shapes.
+ */
+export function featureAnchor(feature) {
+    const geometry = feature.geometry;
+    if (!geometry)
+        return null;
+    const average = (ring) => {
+        const points = ring.length > 1 && ring[0][0] === ring.at(-1)[0] && ring[0][1] === ring.at(-1)[1]
+            ? ring.slice(0, -1)
+            : ring;
+        const [lng, lat] = points.reduce(([x, y], point) => [x + point[0], y + point[1]], [0, 0]);
+        return [lng / points.length, lat / points.length];
+    };
+    switch (geometry.type) {
+        case 'Point':
+            return [geometry.coordinates[0], geometry.coordinates[1]];
+        case 'MultiPoint':
+            return average(geometry.coordinates);
+        case 'LineString': {
+            const middle = geometry.coordinates[Math.floor(geometry.coordinates.length / 2)];
+            return middle ? [middle[0], middle[1]] : null;
+        }
+        case 'MultiLineString':
+            return featureAnchor({
+                ...feature,
+                geometry: { type: 'LineString', coordinates: geometry.coordinates[0] ?? [] },
+            });
+        case 'Polygon':
+            return geometry.coordinates[0]?.length ? average(geometry.coordinates[0]) : null;
+        case 'MultiPolygon':
+            return geometry.coordinates[0]?.[0]?.length ? average(geometry.coordinates[0][0]) : null;
+        default:
+            return geometry.geometries.length
+                ? featureAnchor({ ...feature, geometry: geometry.geometries[0] })
+                : null;
+    }
+}

package/dist/core/equality.d.ts

@@ -0,0 +1,7 @@
+/** Structural equality for the JSON-shaped values in a style: expressions, colours, numbers. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * The properties that differ between two property objects, as `[name, next value]`. A
+ * property that was removed comes back as `undefined`, which resets it to the style default.
+ */
+export declare function changedProperties(previous: Record<string, unknown> | undefined, next: Record<string, unknown> | undefined): Array<[string, unknown]>;

package/dist/core/equality.js

@@ -0,0 +1,33 @@
+/*
+ * Diffing for layer properties, so a re-render sends MapLibre only what changed. Every
+ * `setPaintProperty` call re-validates and repaints; sending the whole paint object on every
+ * change makes a busy map stutter.
+ */
+/** Structural equality for the JSON-shaped values in a style: expressions, colours, numbers. */
+export function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        const other = b;
+        return a.length === other.length && a.every((value, index) => deepEqual(value, other[index]));
+    }
+    const [left, right] = [a, b];
+    const keys = Object.keys(left);
+    return (keys.length === Object.keys(right).length &&
+        keys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key])));
+}
+/**
+ * The properties that differ between two property objects, as `[name, next value]`. A
+ * property that was removed comes back as `undefined`, which resets it to the style default.
+ */
+export function changedProperties(previous, next) {
+    const [before, after] = [previous ?? {}, next ?? {}];
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...keys]
+        .filter((key) => !deepEqual(before[key], after[key]))
+        .map((key) => [key, after[key]]);
+}

package/dist/core/format.d.ts

@@ -0,0 +1,20 @@
+import type { LngLat } from './types.js';
+export interface CoordinateFormat {
+    /** `decimal` → `45.52345° N, 122.67621° W`; `dms` → `45° 31′ 24.4″ N, 122° 40′ 34.4″ W`. */
+    format?: 'decimal' | 'dms';
+    /** Decimal places for `decimal`, or for the seconds in `dms`. */
+    precision?: number;
+}
+/**
+ * A coordinate as people read it: latitude first, with hemispheres rather than signs.
+ * `[-122.676, 45.523]` → `45.52300° N, 122.67600° W`.
+ */
+export declare function formatCoordinate([lng, lat]: LngLat, { format, precision }?: CoordinateFormat): string;
+export interface MeasureFormat {
+    unit?: 'metric' | 'imperial';
+    locale?: string | string[];
+}
+/** `850` → `850 m`, `12400` → `12.4 km`; imperial gives feet and miles. */
+export declare function formatDistance(meters: number, { unit, locale }?: MeasureFormat): string;
+/** `5000` → `5,000 m²`, `2.5e6` → `2.5 km²`; imperial gives acres and square miles. */
+export declare function formatArea(squareMeters: number, { unit, locale }?: MeasureFormat): string;

package/dist/core/format.js

@@ -0,0 +1,47 @@
+function dms(value, precision) {
+    const absolute = Math.abs(value);
+    let degrees = Math.floor(absolute);
+    let minutes = Math.floor((absolute - degrees) * 60);
+    let seconds = Number(((absolute - degrees - minutes / 60) * 3600).toFixed(precision));
+    // Rounding can carry: 59.96″ at one place is 60.0″, which is the next minute.
+    if (seconds >= 60)
+        [seconds, minutes] = [0, minutes + 1];
+    if (minutes >= 60)
+        [minutes, degrees] = [0, degrees + 1];
+    return `${degrees}° ${minutes}′ ${seconds.toFixed(precision)}″`;
+}
+/**
+ * A coordinate as people read it: latitude first, with hemispheres rather than signs.
+ * `[-122.676, 45.523]` → `45.52300° N, 122.67600° W`.
+ */
+export function formatCoordinate([lng, lat], { format = 'decimal', precision = format === 'dms' ? 1 : 5 } = {}) {
+    const part = (value, positive, negative) => `${format === 'dms' ? dms(value, precision) : `${Math.abs(value).toFixed(precision)}°`} ${value >= 0 ? positive : negative}`;
+    return `${part(lat, 'N', 'S')}, ${part(lng, 'E', 'W')}`;
+}
+const number = (value, locale, digits) => new Intl.NumberFormat(locale, { maximumFractionDigits: digits }).format(value);
+/** `850` → `850 m`, `12400` → `12.4 km`; imperial gives feet and miles. */
+export function formatDistance(meters, { unit = 'metric', locale } = {}) {
+    if (unit === 'imperial') {
+        const feet = meters * 3.28084;
+        if (feet < 1000)
+            return `${number(feet, locale, 0)} ft`;
+        const miles = feet / 5280;
+        return `${number(miles, locale, miles < 10 ? 1 : 0)} mi`;
+    }
+    if (meters < 1000)
+        return `${number(meters, locale, 0)} m`;
+    const km = meters / 1000;
+    return `${number(km, locale, km < 10 ? 1 : 0)} km`;
+}
+/** `5000` → `5,000 m²`, `2.5e6` → `2.5 km²`; imperial gives acres and square miles. */
+export function formatArea(squareMeters, { unit = 'metric', locale } = {}) {
+    if (unit === 'imperial') {
+        const acres = squareMeters / 4046.8564224;
+        if (acres < 640)
+            return `${number(acres, locale, acres < 10 ? 2 : 1)} ac`;
+        return `${number(acres / 640, locale, 1)} mi²`;
+    }
+    if (squareMeters < 1e6)
+        return `${number(squareMeters, locale, 0)} m²`;
+    return `${number(squareMeters / 1e6, locale, 1)} km²`;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,16 @@
+export * from './types.js';
+export * from './bounds.js';
+export * from './format.js';
+export * from './style.js';
+export * from './data.js';
+export * from './equality.js';
+export * from './cluster.js';
+export * from './accessibility.js';
+export * from './route.js';
+export * from './spatial.js';
+export * from './simplify.js';
+export * from './lod.js';
+export { createSpatialWorker } from './workers/client.js';
+export type { SpatialWorker, SpatialWorkerOptions } from './workers/client.js';
+export { createSpatialHandler } from './workers/handler.js';
+export type { SpatialRequest, SpatialResponse } from './workers/protocol.js';

package/dist/core/index.js

@@ -0,0 +1,18 @@
+/*
+ * Plain TypeScript with no Svelte and no MapLibre import: styles, geometry, formatting and
+ * GeoJSON helpers that run anywhere — the server, a worker, a test.
+ */
+export * from './types.js';
+export * from './bounds.js';
+export * from './format.js';
+export * from './style.js';
+export * from './data.js';
+export * from './equality.js';
+export * from './cluster.js';
+export * from './accessibility.js';
+export * from './route.js';
+export * from './spatial.js';
+export * from './simplify.js';
+export * from './lod.js';
+export { createSpatialWorker } from './workers/client.js';
+export { createSpatialHandler } from './workers/handler.js';

package/dist/core/lod.d.ts

@@ -0,0 +1,27 @@
+import type { Feature, FeatureCollection } from './types.js';
+/**
+ * The simplification tolerance, in degrees, that keeps error under `pixels` at `zoom` — about
+ * the width of one screen pixel of longitude at the equator.
+ */
+export declare function toleranceForZoom(zoom: number, { pixels, tileSize }?: {
+    pixels?: number | undefined;
+    tileSize?: number | undefined;
+}): number;
+export interface LevelOfDetail<P> {
+    /** The collection simplified for `zoom`, cached per whole zoom level. */
+    at(zoom: number): FeatureCollection<P>;
+    clear(): void;
+}
+/**
+ * Precomputes nothing; simplifies on demand and caches per whole zoom level, so panning at one
+ * zoom costs nothing and zooming costs one pass. At `maxZoom` and above the data is untouched.
+ */
+export declare function createLevelOfDetail<P>(collection: FeatureCollection<P>, { pixels, maxZoom }?: {
+    pixels?: number;
+    maxZoom?: number;
+}): LevelOfDetail<P>;
+/**
+ * A group of features as one outline — the convex hull of every coordinate — for drawing a
+ * whole set as a single shape when zoomed far out. `null` for fewer than three distinct points.
+ */
+export declare function outlineOf<P extends Record<string, unknown>>(features: Array<Feature>, properties?: P): Feature<P> | null;

package/dist/core/lod.js

@@ -0,0 +1,49 @@
+import { convexHull, simplifyFeatures } from './simplify.js';
+import { coordinatesOf } from './bounds.js';
+/*
+ * Level of detail: draw less when zoomed out. Shapes are simplified to what a pixel can show at
+ * the current zoom, and a group of features can collapse into its outline.
+ */
+/**
+ * The simplification tolerance, in degrees, that keeps error under `pixels` at `zoom` — about
+ * the width of one screen pixel of longitude at the equator.
+ */
+export function toleranceForZoom(zoom, { pixels = 1, tileSize = 512 } = {}) {
+    return (360 / (tileSize * 2 ** zoom)) * pixels;
+}
+/**
+ * Precomputes nothing; simplifies on demand and caches per whole zoom level, so panning at one
+ * zoom costs nothing and zooming costs one pass. At `maxZoom` and above the data is untouched.
+ */
+export function createLevelOfDetail(collection, { pixels = 1, maxZoom = 16 } = {}) {
+    const cache = new Map();
+    return {
+        at(zoom) {
+            const level = Math.max(0, Math.floor(zoom));
+            if (level >= maxZoom)
+                return collection;
+            let simplified = cache.get(level);
+            if (!simplified) {
+                simplified = simplifyFeatures(collection, toleranceForZoom(level, { pixels }));
+                cache.set(level, simplified);
+            }
+            return simplified;
+        },
+        clear: () => cache.clear(),
+    };
+}
+/**
+ * A group of features as one outline — the convex hull of every coordinate — for drawing a
+ * whole set as a single shape when zoomed far out. `null` for fewer than three distinct points.
+ */
+export function outlineOf(features, properties = {}) {
+    const points = [];
+    for (const feature of features) {
+        for (const position of coordinatesOf(feature))
+            points.push([position[0], position[1]]);
+    }
+    const hull = convexHull(points);
+    if (hull.length < 4)
+        return null;
+    return { type: 'Feature', geometry: { type: 'Polygon', coordinates: [hull] }, properties };
+}

package/dist/core/route.d.ts

@@ -0,0 +1,58 @@
+import type { LngLat } from './types.js';
+/** Mean earth radius, in metres (IUGG). */
+export declare const EARTH_RADIUS = 6371008.8;
+/** Great-circle distance in metres. `NaN` when either point is not a real coordinate. */
+export declare function haversine(a: LngLat, b: LngLat): number;
+/** The length of a path through `points`, in metres. */
+export declare const pathLength: (points: LngLat[]) => number;
+/** Every pairwise distance, in metres. Symmetric, with zeros on the diagonal. */
+export declare function distanceMatrix(points: LngLat[]): number[][];
+export interface RouteOrder {
+    /** Indexes into the stops, in visiting order. */
+    order: number[];
+    /** Each leg's length in metres: origin to the first stop, then stop to stop. */
+    legs: number[];
+    /** The whole route, in metres. Legs that cannot be measured count as zero. */
+    total: number;
+}
+/**
+ * Improves an order by reversing any stretch that shortens the route, until none does (2-opt).
+ * The route starts at `origin` and ends at its last stop; it does not return.
+ */
+export declare function twoOpt(origin: LngLat, points: LngLat[], order: number[], { maxPasses, matrix, }?: {
+    maxPasses?: number;
+    matrix?: number[][];
+}): number[];
+/**
+ * A short order to visit `stops` from `origin`: nearest neighbour first, then 2-opt. Not the
+ * shortest possible — that problem is intractable — but close for a day's worth of stops.
+ */
+export declare function optimizeRoute(origin: LngLat, stops: LngLat[], { improve, maxPasses }?: {
+    improve?: boolean;
+    maxPasses?: number;
+}): RouteOrder;
+/** Legs and total for an order you already have, to compare against an optimised one. */
+export declare const measureRoute: (origin: LngLat, stops: LngLat[], order: number[]) => RouteOrder;
+/** A stop for a directions link: a coordinate, or an address to search for. */
+export type RouteStop = LngLat | string;
+/** Google Maps allows this many stops between origin and destination in one link. */
+export declare const GOOGLE_MAX_WAYPOINTS = 9;
+export interface DirectionsOptions {
+    /** Where the trip starts. Leave it out to start from the user's location. */
+    origin?: RouteStop;
+    travelMode?: 'driving' | 'walking' | 'bicycling' | 'transit';
+}
+/** A Google Maps directions link through `stops`, the last being the destination. */
+export declare function googleDirectionsUrl(stops: RouteStop[], { origin, travelMode }?: DirectionsOptions): string;
+/** An Apple Maps directions link through `stops`. */
+export declare function appleDirectionsUrl(stops: RouteStop[], { origin, travelMode }?: DirectionsOptions): string;
+/**
+ * Splits a long list of stops into legs that each fit one link, every leg starting where the
+ * last one ended.
+ */
+export declare function splitIntoLegs<T>(stops: T[], maxPerLeg?: number): T[][];
+/**
+ * Google Maps links for a route too long for one: one per leg, each starting where the last one
+ * ended. A leg holds an origin, up to nine waypoints and a destination.
+ */
+export declare function googleDirectionsLegUrls(stops: RouteStop[], options?: DirectionsOptions): string[];