@goway.to/maps 0.0.0-stage → 0.1.0

package/dist/shared.js

@@ -0,0 +1,337 @@
+/**
+ * Translation helpers shared by the two engine forks.
+ *
+ * This is the ONLY place GoWay's `{ latitude, longitude }` becomes MapLibre's
+ * `[longitude, latitude]` — once, tested by both forks using it, rather than at
+ * every call site where a swapped pair renders a plausible map of the wrong
+ * place and nothing errors.
+ *
+ * It is also the gate. `isDrawableCoordinate` / `drawableMarkers` /
+ * `isDrawableBounds` / `resolvePadding` / `asFinite` keep a `NaN` from reaching
+ * an engine, which is a THROW rather than a bad frame — see the block comment
+ * above {@link isDrawableCoordinate}. `isDrawableGeoJSON` covers the one path
+ * that fails the OTHER way: raw GeoJSON does not throw, it renders nowhere and
+ * says nothing. `optionalScalar` covers the third: a key that is PRESENT and
+ * `undefined` is not the same as an absent one, and an engine that defaults the
+ * absent one does not default this one.
+ *
+ * And `runEngineCommand` is the floor under all of it: whatever still gets
+ * through, an engine call that throws costs the CALL, not the application.
+ */
+import { unwrappedEast } from '@goway.to/sdk/geo';
+export function toLngLat(coordinate) {
+    return [coordinate.longitude, coordinate.latitude];
+}
+export function fromLngLat(position) {
+    return { longitude: position[0], latitude: position[1] };
+}
+/**
+ * A box in engine order, its east edge carried past 180 when it crosses the
+ * antimeridian so both engines frame the strip it describes.
+ */
+export function toBoundsArray(bounds) {
+    return [bounds.west, bounds.south, unwrappedEast(bounds), bounds.north];
+}
+/** Every interaction is on unless a caller turns it off. */
+export function resolveInteraction(options) {
+    return {
+        pan: options?.pan ?? true,
+        zoom: options?.zoom ?? true,
+        rotate: options?.rotate ?? true,
+        pitch: options?.pitch ?? true,
+    };
+}
+/**
+ * Normalise a `moveTo` target: a bare coordinate leaves the camera's zoom alone.
+ *
+ * `Number.isFinite`, not `typeof === 'number'` — `typeof NaN` IS `'number'`, so
+ * the old test accepted `{ latitude, longitude, zoom: NaN }` as a viewport and
+ * passed that `NaN` on to the engine. See {@link asFinite} for what that costs.
+ * A viewport whose zoom is not a number is treated as the bare coordinate it
+ * usefully is.
+ */
+export function isViewport(target) {
+    return Number.isFinite(target.zoom);
+}
+/**
+ * A camera scalar the engine can use, or `undefined`.
+ *
+ * Zoom, bearing, pitch, duration and maxZoom are the seam's unchecked numbers,
+ * and a `NaN` in any of them is not a bad frame — it is the SAME crash a bad
+ * coordinate is, one step later. `transform.setZoom(NaN)` survives MapLibre's
+ * own `clamp` (every comparison against `NaN` is false), so `_scale` and
+ * `worldSize` become `NaN`; the next unprojection — `map.getBounds()`, which
+ * this canvas calls on every `move` event, and which `jumpTo` fires
+ * SYNCHRONOUSLY — builds a `LngLat` out of two `NaN`s and throws
+ * `Invalid LngLat object: (NaN, NaN)` from inside the caller's own React
+ * handler. The camera simply not moving is the better failure.
+ */
+export function asFinite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * A scalar an engine's options object may carry — or NOTHING AT ALL.
+ *
+ * ## The defect this exists to remove
+ *
+ * `{ maxZoom: undefined }` and `{}` look interchangeable in TypeScript, and to
+ * MapLibre GL JS they are opposites. `Map._cameraForBoxAndBearing` fills in its
+ * own defaults with
+ *
+ * ```
+ * options = extend({ padding, offset: [0, 0], maxZoom: this.transform.maxZoom }, options);
+ * ```
+ *
+ * and `extend` is `for (const k in src) dest[k] = src[k]` — an OWN key wins
+ * even when its value is `undefined`. So passing the key at all replaces the
+ * engine's maximum zoom with `undefined`, and the very next line is
+ *
+ * ```
+ * const zoom = Math.min(scaleZoom(tr.scale * Math.min(scaleX, scaleY)), options.maxZoom);
+ * ```
+ *
+ * `Math.min(anything, undefined)` is `NaN`. That `NaN` divides into
+ * `offsetAtFinalZoom`, reaches the centre `cameraForBoxAndBearing` unprojects,
+ * and `new LngLat(NaN, NaN)` THROWS — from inside the React effect that asked
+ * for the fit, which is the error boundary and the whole app. Omitting the key
+ * is the only way to mean "use yours".
+ *
+ * Every optional scalar this seam forwards therefore goes through here, so
+ * "the caller did not say" can never arrive as "the caller said nothing".
+ */
+export function optionalScalar(key, value) {
+    const finite = asFinite(value);
+    return finite === undefined ? {} : { [key]: finite };
+}
+/**
+ * Fit padding, expanded to the four-sided form both engines want — or `null`
+ * when it is not a number the engine can use.
+ *
+ * See {@link isDrawableCoordinate} for why a non-finite number is refused here
+ * rather than passed on: MapLibre's `cameraForBoxAndBearing` divides the free
+ * viewport by the padding, and `NaN` propagates all the way to the LngLat it
+ * constructs for the new centre, which throws. A NEGATIVE padding does not
+ * throw, but it is never what a caller meant (it frames content OUTSIDE the
+ * viewport), and a negative pair is one of the ways the free space lands on
+ * exactly zero, which does throw. So negatives clamp to zero and non-finite
+ * values refuse the fit outright.
+ */
+export function resolvePadding(padding, fallback) {
+    const raw = padding == null
+        ? { top: fallback, right: fallback, bottom: fallback, left: fallback }
+        : typeof padding === 'number'
+            ? { top: padding, right: padding, bottom: padding, left: padding }
+            : padding;
+    if (!Number.isFinite(raw.top) ||
+        !Number.isFinite(raw.right) ||
+        !Number.isFinite(raw.bottom) ||
+        !Number.isFinite(raw.left)) {
+        reportMapDefect('padding:non-finite', `Refusing a fit: padding is not finite (${describeNumbers(raw)}).`);
+        return null;
+    }
+    return {
+        top: Math.max(0, raw.top),
+        right: Math.max(0, raw.right),
+        bottom: Math.max(0, raw.bottom),
+        left: Math.max(0, raw.left),
+    };
+}
+// ---------------------------------------------------------------------------
+// The garbage gate
+// ---------------------------------------------------------------------------
+/**
+ * Both MapLibre engines build a `LngLat` out of whatever they are handed, and
+ * `LngLat` THROWS on a non-number — `Invalid LngLat object: (NaN, NaN)`. Thrown
+ * from a React effect (setting a marker's position, framing a route) that
+ * reaches the nearest error boundary, so one bad pin takes the whole screen
+ * down and the user sees "Something went wrong" instead of a map.
+ *
+ * `@goway.to/maps` is the single seam every coordinate crosses on its way to
+ * an engine, so it is where that stops being possible. A marker whose
+ * coordinate is not drawable is DROPPED (a map missing one pin is a degraded
+ * map; a map that throws is no map) and a camera move whose target is not
+ * drawable is a no-op.
+ *
+ * ## Why this is not `isValidCoordinate`
+ *
+ * `@goway.to/sdk/geo`'s `isValidCoordinate` is the PRODUCT's rule — a real point
+ * on the earth, longitude within ±180. This is the ENGINE's rule, which is
+ * looser on longitude on purpose: MapLibre reports unwrapped longitudes across
+ * the antimeridian (a click at 181°E comes back as 181, not −179), and feeding
+ * one of those back in is legal and does the right thing. Rejecting it here
+ * would break panning past the date line in the name of safety. Latitude is
+ * bounded, because `LngLat` throws outside ±90 too.
+ */
+export function isDrawableCoordinate(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const { latitude, longitude } = value;
+    return (Number.isFinite(longitude) && Number.isFinite(latitude) && latitude >= -90 && latitude <= 90);
+}
+/** The same rule as {@link isDrawableCoordinate}, applied to a box's corners. */
+export function isDrawableBounds(bounds) {
+    if (!bounds)
+        return false;
+    return (isDrawableCoordinate({ latitude: bounds.south, longitude: bounds.west }) &&
+        isDrawableCoordinate({ latitude: bounds.north, longitude: bounds.east }));
+}
+/**
+ * The markers an engine may be given, with the undrawable ones removed.
+ *
+ * Returns the INPUT ARRAY when nothing is wrong, so the common path adds one
+ * pass and no allocation, and the forks' effect dependencies do not change
+ * identity every render.
+ */
+export function drawableMarkers(markers) {
+    if (!markers || markers.length === 0)
+        return EMPTY_MARKERS;
+    let firstBad = -1;
+    for (let index = 0; index < markers.length; index += 1) {
+        if (!isDrawableCoordinate(markers[index].coordinate)) {
+            firstBad = index;
+            break;
+        }
+    }
+    if (firstBad < 0)
+        return markers;
+    const kept = markers.slice(0, firstBad);
+    for (let index = firstBad; index < markers.length; index += 1) {
+        const marker = markers[index];
+        if (isDrawableCoordinate(marker.coordinate)) {
+            kept.push(marker);
+            continue;
+        }
+        reportMapDefect(`marker:${marker.id}`, `Dropped marker "${marker.id}": coordinate is not drawable (${describeNumbers(marker.coordinate)}).`);
+    }
+    return kept;
+}
+const EMPTY_MARKERS = [];
+/**
+ * Every position in a GeoJSON document is a point the engine can project, and
+ * every geometry has enough of them to BE that geometry.
+ *
+ * The arity check is not pedantry about RFC 7946: a one-point `LineString` and
+ * an empty ring are exactly what a mis-sliced route produces, they draw
+ * nothing, and they are indistinguishable from "the route did not arrive"
+ * unless something says so.
+ *
+ * A composite geometry needs the same check one level up, for the same reason
+ * and one that is easier to miss: `[].every()` is `true`, so an empty
+ * `coordinates` array satisfies every per-part rule vacuously. An empty
+ * `Polygon` has no ring that can fail `ring()`, and a `MultiPolygon` of `[[]]`
+ * has no polygon that can. Both are what a slice that matched nothing
+ * produces, both reach the engine, and both draw exactly nothing — so every
+ * composite array is required to be non-empty BEFORE its parts are checked.
+ */
+export function isDrawableGeoJSON(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    switch (data.type) {
+        case 'FeatureCollection':
+            return Array.isArray(data.features) && data.features.every((f) => isDrawableGeoJSON(f));
+        case 'Feature':
+            // A null geometry is legal GeoJSON and draws nothing, which for an
+            // overlay is the same as not being there.
+            return data.geometry != null && isDrawableGeoJSON(data.geometry);
+        case 'GeometryCollection':
+            return (Array.isArray(data.geometries) &&
+                data.geometries.length > 0 &&
+                data.geometries.every((g) => isDrawableGeoJSON(g)));
+        case 'Point':
+            return isDrawablePosition(data.coordinates);
+        case 'MultiPoint':
+            return ring(data.coordinates, 1);
+        case 'LineString':
+            return ring(data.coordinates, 2);
+        case 'MultiLineString':
+            return nonEmpty(data.coordinates) && data.coordinates.every((l) => ring(l, 2));
+        case 'Polygon':
+            return nonEmpty(data.coordinates) && data.coordinates.every((r) => ring(r, 4));
+        case 'MultiPolygon':
+            return (nonEmpty(data.coordinates) &&
+                data.coordinates.every((p) => nonEmpty(p) && p.every((r) => ring(r, 4))));
+        default:
+            return false;
+    }
+}
+function ring(positions, minimum) {
+    return (Array.isArray(positions) && positions.length >= minimum && positions.every(isDrawablePosition));
+}
+/**
+ * An array with something in it.
+ *
+ * `[].every()` is `true`, so a composite geometry whose only check is `every`
+ * accepts the empty case: `{ type: 'Polygon', coordinates: [] }` has no ring to
+ * fail `ring()` and passed every test above. That is the exact silent failure
+ * this module exists to catch — a geometry the engine accepts, tiles, and draws
+ * nothing for — so the outer array is checked before the inner ones are.
+ */
+function nonEmpty(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+/** A GeoJSON position is `[longitude, latitude]`, altitude optional. */
+function isDrawablePosition(position) {
+    if (!Array.isArray(position) || position.length < 2)
+        return false;
+    return isDrawableCoordinate({ longitude: position[0], latitude: position[1] });
+}
+/**
+ * Say it ONCE per defect.
+ *
+ * Markers are re-applied on every camera frame a parent reacts to, so a
+ * per-occurrence warning would be thousands of identical lines during a single
+ * drag — which is how a real signal becomes noise somebody mutes. The key is
+ * the marker id (or the kind of camera defect), so a second, different bad pin
+ * is still reported.
+ */
+const reported = new Set();
+export function reportMapDefect(key, message) {
+    if (reported.has(key))
+        return;
+    reported.add(key);
+    console.warn(`[goway/maps] ${message}`);
+}
+/**
+ * Run one engine command, and let a throw cost the COMMAND rather than the app.
+ *
+ * This is the BACKSTOP, deliberately separate from the checks above. Those
+ * refuse the bad values we know about; this one is for the ones we do not. Every
+ * guard in this file was written after a crash, which is the evidence that the
+ * next non-finite number will arrive from somewhere nobody predicted — a
+ * renderer upgrade that starts rejecting an input it used to accept, a new
+ * option forwarded through an unexamined path, a device API that changes shape.
+ *
+ * What makes that catastrophic rather than cosmetic is WHERE these calls run:
+ * a camera move issued from a `useEffect` throws inside React's commit phase,
+ * so the nearest error boundary unmounts the tree and the user gets "Something
+ * went wrong" instead of a map. A camera that did not move is a map. That is
+ * the whole trade, and it is not close.
+ *
+ * It is not a licence to stop validating: a swallowed throw is a `console.warn`
+ * nobody reads, so anything we can name is still refused BEFORE it gets here,
+ * by a check that says which value was wrong and why.
+ *
+ * Answers whether the command ran: `false` is a dropped command, which a
+ * caller waiting on its outcome (a camera move's settle) must not wait for.
+ */
+export function runEngineCommand(command, run) {
+    try {
+        run();
+        return true;
+    }
+    catch (cause) {
+        reportMapDefect(`engine:${command}`, `The map engine threw on "${command}" and the command was dropped: ${String(cause)}`);
+        return false;
+    }
+}
+/**
+ * `key NaN` — never `JSON.stringify`, which prints `NaN` and `Infinity` as
+ * `null` and so erases the one detail the reader needs.
+ */
+export function describeNumbers(value) {
+    if (!value || typeof value !== 'object')
+        return String(value);
+    return Object.entries(value)
+        .map(([key, entry]) => `${key} ${String(entry)}`)
+        .join(', ');
+}

package/dist/sourceContext.d.ts

@@ -0,0 +1,2 @@
+export declare const SourceIdContext: import("react").Context<string | null>;
+export declare function useSourceId(): string;

package/dist/sourceContext.js

@@ -0,0 +1,9 @@
+/** The id of the source a `<Layer>` draws: the `<GeoJSONSource>` / `<RasterDEMSource>` around it. */
+import { createContext, useContext } from 'react';
+export const SourceIdContext = createContext(null);
+export function useSourceId() {
+    const id = useContext(SourceIdContext);
+    if (!id)
+        throw new Error('A <Layer> must be rendered inside a source (<GeoJSONSource>, <RasterDEMSource>).');
+    return id;
+}

package/dist/styleUrl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which style document a map draws.
+ *
+ * `goway://styles/<id>` is GoWay's name for a published style, as
+ * `mapbox://styles/...` is Mapbox's; `@goway.to/sdk` resolves it to its
+ * document on goway.to. A GoWay style that follows the light is drawn in the
+ * app's theme — day in light mode, night in dark — unless the screen pins a
+ * light. Any other URL is used as it is.
+ */
+import { type MapLightPreset } from '@goway.to/sdk';
+/** The style a `MapView` draws when it is given none: GoWay Standard. */
+export declare const DEFAULT_MAP_STYLE: string;
+/**
+ * The document URL for `mapStyle`, in `lightPreset` or the theme's light.
+ * Throws `GoWayValidationError` for a `goway://` name that is not a published
+ * style — the map reports that as a style failure rather than drawing a
+ * different map than the one asked for.
+ */
+export declare function resolveStyleUrl(mapStyle: string, lightPreset: MapLightPreset | undefined, dark: boolean): string;

package/dist/styleUrl.js

@@ -0,0 +1,22 @@
+/**
+ * Which style document a map draws.
+ *
+ * `goway://styles/<id>` is GoWay's name for a published style, as
+ * `mapbox://styles/...` is Mapbox's; `@goway.to/sdk` resolves it to its
+ * document on goway.to. A GoWay style that follows the light is drawn in the
+ * app's theme — day in light mode, night in dark — unless the screen pins a
+ * light. Any other URL is used as it is.
+ */
+import { createGoWayClient, gowayStyleUrl } from '@goway.to/sdk';
+/** The style a `MapView` draws when it is given none: GoWay Standard. */
+export const DEFAULT_MAP_STYLE = gowayStyleUrl('standard');
+const links = createGoWayClient().links;
+/**
+ * The document URL for `mapStyle`, in `lightPreset` or the theme's light.
+ * Throws `GoWayValidationError` for a `goway://` name that is not a published
+ * style — the map reports that as a style failure rather than drawing a
+ * different map than the one asked for.
+ */
+export function resolveStyleUrl(mapStyle, lightPreset, dark) {
+    return links.styleUrl(mapStyle, lightPreset ?? (dark ? 'night' : 'day'));
+}

package/dist/testing.d.ts

@@ -0,0 +1,41 @@
+import type { MapCameraChange } from './types';
+export { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT } from './cameraReports.web';
+export interface FakeCamera {
+    lat: number;
+    lng: number;
+    zoom: number;
+    bearing: number;
+    pitch: number;
+    /** Half the box's height and width, in degrees: a bigger container, a bigger box. */
+    span: number;
+}
+export declare function fakeCameraEngine(start?: Partial<FakeCamera>): {
+    camera: FakeCamera;
+    fire(type: string, event?: object): void;
+    /** A whole camera move, as MapLibre fires it, ending wherever `to` says. */
+    move(event: object, to?: Partial<FakeCamera>): void;
+    listenerCount: () => number;
+    on(type: string, listener: (event: unknown) => void): /*elided*/ any;
+    off(type: string, listener: (event: unknown) => void): /*elided*/ any;
+    getCenter: () => {
+        lat: number;
+        lng: number;
+    };
+    getBounds: () => {
+        getWest: () => number;
+        getSouth: () => number;
+        getEast: () => number;
+        getNorth: () => number;
+    };
+    getZoom: () => number;
+    getBearing: () => number;
+    getPitch: () => number;
+};
+export type FakeCameraEngine = ReturnType<typeof fakeCameraEngine>;
+/** Attach the real reports to a fake engine; `withListener: false` is the embed. */
+export declare function attachToFake(engine: FakeCameraEngine, withListener?: boolean): {
+    changes: MapCameraChange[];
+    detach: () => void;
+    finals: () => MapCameraChange[];
+    advance(ms: number): void;
+};

package/dist/testing.js

@@ -0,0 +1,80 @@
+/**
+ * `@goway.to/maps/testing` — drive the map's REAL camera reports without a GPU.
+ *
+ * What a screen does with `onCameraChanged` (arm "Search this area", commit a
+ * box, pause a tour) is the screen's logic, and the sequences that matter —
+ * the opening camera, a programmatic frame, the reader's drag — are the ones a
+ * loading map produces. `fakeCameraEngine` is a MapLibre map as far as the
+ * reports see it (the events it fires and the camera it reads; the real one
+ * needs WebGL), and `attachToFake` runs the SDK's own web reporting on it.
+ *
+ *     const engine = fakeCameraEngine({ lat: 41.39, lng: 2.17, zoom: 11 });
+ *     const reports = attachToFake(engine);
+ *     engine.fire('load');
+ *     engine.move({ originalEvent: {} }, { lng: 2.2 });   // the reader drags
+ *     engine.move(PROGRAMMATIC, { zoom: 14 });            // the app frames
+ */
+import { attachCameraReports } from './cameraReports.web';
+export { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT } from './cameraReports.web';
+export function fakeCameraEngine(start = {}) {
+    const listeners = new Map();
+    const camera = {
+        lat: 41.4036,
+        lng: 2.1744,
+        zoom: 16.5,
+        bearing: 30,
+        pitch: 60,
+        span: 0.01,
+        ...start,
+    };
+    const engine = {
+        camera,
+        fire(type, event = {}) {
+            for (const listener of listeners.get(type) ?? [])
+                listener({ type, ...event });
+        },
+        /** A whole camera move, as MapLibre fires it, ending wherever `to` says. */
+        move(event, to = {}) {
+            engine.fire('movestart', event);
+            Object.assign(camera, to);
+            engine.fire('move', event);
+            engine.fire('moveend', event);
+        },
+        listenerCount: () => [...listeners.values()].reduce((sum, set) => sum + set.size, 0),
+        on(type, listener) {
+            if (!listeners.has(type))
+                listeners.set(type, new Set());
+            listeners.get(type)?.add(listener);
+            return engine;
+        },
+        off(type, listener) {
+            listeners.get(type)?.delete(listener);
+            return engine;
+        },
+        getCenter: () => ({ lat: camera.lat, lng: camera.lng }),
+        getBounds: () => ({
+            getWest: () => camera.lng - camera.span,
+            getSouth: () => camera.lat - camera.span,
+            getEast: () => camera.lng + camera.span,
+            getNorth: () => camera.lat + camera.span,
+        }),
+        getZoom: () => camera.zoom,
+        getBearing: () => camera.bearing,
+        getPitch: () => camera.pitch,
+    };
+    return engine;
+}
+/** Attach the real reports to a fake engine; `withListener: false` is the embed. */
+export function attachToFake(engine, withListener = true) {
+    const changes = [];
+    let clock = 0;
+    const detach = attachCameraReports(engine, () => (withListener ? (change) => changes.push(change) : undefined), () => clock);
+    return {
+        changes,
+        detach,
+        finals: () => changes.filter((change) => change.isFinal),
+        advance(ms) {
+            clock += ms;
+        },
+    };
+}