@goway.to/maps 0.0.0-stage → 0.1.0

package/dist/labels.js

@@ -0,0 +1,451 @@
+/**
+ * The basemap's own labels, as GoWay-shaped things.
+ *
+ * The vector tiles have always carried the names — POIs, streets, rivers,
+ * districts, cities — and GoWay's style has always drawn them. Until this
+ * module they were PAINT: `map.on('click')` reported a coordinate and nothing
+ * ever asked the engine what was under the finger. Every name on the map was
+ * dead pixels, while GoWay drew its own chips on top of some of them.
+ *
+ * This file is where a tapped tile feature stops being the engine's and becomes
+ * GoWay's. Both engine forks query their own engine (`queryRenderedFeatures`
+ * on web, `MapRef.queryRenderedFeatures` on native), flatten each hit into a
+ * {@link QueriedLabel}, and hand the list here; what comes back is a
+ * {@link MapLabelFeature}, the only shape an app ever sees. The flattening
+ * happens in the forks and the RANKING happens here: the rule that decides
+ * which of five overlapping labels a tap meant must be identical on iOS and on
+ * the web, and it is testable only if it is a pure function.
+ *
+ * ## Every text on the map, not just the shop pins
+ *
+ * {@link LABEL_SOURCE_LAYERS} covers all six source-layers GoWay's style draws
+ * a name from: POIs, places (city → neighbourhood), parks, aerodromes, peaks,
+ * street names, water bodies and waterways. A tappable shop beside a dead
+ * street name is the inconsistency a user notices first.
+ *
+ * ## What was measured, rather than assumed
+ *
+ * Driving headless Chromium against the real GoWay style and real OpenFreeMap
+ * tiles over Barcelona:
+ *
+ *  - A query at the EXACT pixel of a POI's anchor returns the dot and nothing
+ *    else; six pixels away it returns nothing at all. A label glyph is a few
+ *    pixels tall and `text-anchor: top` puts the text BELOW the anchor, so the
+ *    thing a user aims at and the point the engine indexes are 12–20 px apart.
+ *    That is why {@link LABEL_HIT_PAD_PX} exists and why it is not 2.
+ *  - A padded box of 10 px catches both the dot and its label across the whole
+ *    band; a tap on empty ground still returns `[]`, so a generous pad does not
+ *    manufacture hits.
+ *  - `queryRenderedFeatures` on the symbol layers returned 16 labels where the
+ *    loaded source held 3185 POI features in the same view. It answers with
+ *    what the collision system actually PLACED, not with what the tiles
+ *    contain.
+ */
+import { OPENMAPTILES_SOURCE_LAYERS as SL } from '@goway.to/sdk';
+import { isDrawableCoordinate } from './shared';
+/**
+ * How far around the tap the engine is asked to look, in px (web) / dp (native).
+ *
+ * The measurement above says 10 px is the minimum that reaches both a POI's dot
+ * and its label. 18 is that plus finger slop, and a generous pad costs nothing
+ * because {@link pickLabelFeature} resolves a crowded box by distance — the
+ * nearest label still wins, so widening the net changes what a sloppy tap hits
+ * and never what an accurate one hits.
+ *
+ * One number for mouse and touch on purpose. Sniffing the pointer type is
+ * unreliable (a browser-synthesised click from a touch is an ordinary
+ * `MouseEvent`), and a click 14 px from a label is a click that meant the
+ * label: a tap on genuinely empty ground was measured to return nothing at any
+ * pad, so the failure this could cause — "I clicked nothing and got something"
+ * — has nothing to be caused by.
+ */
+export const LABEL_HIT_PAD_PX = 18;
+/**
+ * Source-layers a tap may resolve against, in the OpenMapTiles v3 vocabulary.
+ *
+ * Read from GoWay's tile schema (`@goway.to/sdk`) rather than spelled here: a
+ * wrong source-layer name is the failure mode that logs nothing and throws
+ * nothing, and the schema is the one place those names are recorded.
+ *
+ * This is every layer GoWay's style puts a NAME on. `transportation` is absent
+ * although the style draws a symbol from it — that symbol is `road-oneway`, an
+ * arrow, and an arrow is not a label. `building` and `housenumber` are absent
+ * because a house number is an address fragment, not a thing with a name.
+ */
+export const LABEL_SOURCE_LAYERS = [
+    SL.poi,
+    SL.place,
+    SL.park,
+    SL.aerodromeLabel,
+    SL.mountainPeak,
+    SL.transportationName,
+    SL.waterName,
+    SL.waterway,
+];
+const LABEL_SOURCE_LAYER_SET = new Set(LABEL_SOURCE_LAYERS);
+/**
+ * The name the basemap is DRAWING, or `null`.
+ *
+ * Exactly `coalesce(name:latin, name)` — the `text-field` expression of
+ * GoWay's styles. Not `name_en`, not `name_int`: a label that says
+ * one thing on screen and another in the sheet is a worse bug than no sheet,
+ * and the user tapped what they could read.
+ */
+export function labelNameOf(properties) {
+    const latin = properties['name:latin'];
+    if (typeof latin === 'string' && latin.trim())
+        return latin.trim();
+    const name = properties.name;
+    if (typeof name === 'string' && name.trim())
+        return name.trim();
+    return null;
+}
+/**
+ * What kind of named thing this is, decided by SOURCE-LAYER rather than by
+ * guesswork over the name.
+ *
+ * Four kinds, because four is what the product acts on differently — see
+ * `MapLabelKind` in `types.ts` for what each one means and what a tap on it
+ * does.
+ */
+export function labelKindOf(sourceLayer) {
+    switch (sourceLayer) {
+        case SL.poi:
+        case SL.aerodromeLabel:
+            return 'poi';
+        case SL.place:
+        case SL.park:
+        case SL.mountainPeak:
+            return 'area';
+        case SL.transportationName:
+            return 'road';
+        case SL.waterName:
+        case SL.waterway:
+            return 'water';
+        default:
+            return null;
+    }
+}
+/** Whether a source-layer can answer a tap at all. */
+export function isLabelSourceLayer(sourceLayer) {
+    return LABEL_SOURCE_LAYER_SET.has(sourceLayer);
+}
+/**
+ * One queried hit as a GoWay label, or `null` when it is not one.
+ *
+ * `fallback` is where the user tapped. It is used when the feature has no
+ * anchor of its own — a label placed over a POLYGON, such as a park, whose name
+ * sits at the pole of inaccessibility that exists only inside MapLibre's
+ * placement and not in the tile. The tap is inside the polygon by construction,
+ * so it is a truthful point for that thing.
+ *
+ * Anything derived from a queried geometry goes through `isDrawableCoordinate`
+ * for the reason the whole seam exists — a `NaN` reaching MapLibre is a THROW
+ * out of the effect that positions things, not a misplaced pin (see
+ * `shared.ts`).
+ */
+export function toLabelFeature(candidate, fallback, anchor) {
+    const kind = labelKindOf(candidate.sourceLayer);
+    if (!kind)
+        return null;
+    const name = labelNameOf(candidate.properties);
+    if (!name)
+        return null;
+    const own = anchor ?? candidate.coordinate;
+    const anchored = isDrawableCoordinate(own);
+    const coordinate = anchored ? own : fallback;
+    if (!isDrawableCoordinate(coordinate))
+        return null;
+    const category = stringProp(candidate.properties, 'class');
+    const subcategory = stringProp(candidate.properties, 'subclass');
+    const rank = numberProp(candidate.properties, 'rank');
+    return {
+        // The tiles' feature id where there is one, and a coordinate-derived id
+        // where there is not, so a label is always keyable. It is NOT a GoWay Place
+        // ID and cannot be joined to one — see the note in `types.ts`.
+        id: candidate.featureId == null
+            ? `${candidate.sourceLayer}:${coordinate.longitude.toFixed(6)},${coordinate.latitude.toFixed(6)}`
+            : `${candidate.sourceLayer}:${String(candidate.featureId)}`,
+        name,
+        kind,
+        coordinate,
+        anchored,
+        ...(category ? { category } : {}),
+        ...(subcategory ? { subcategory } : {}),
+        ...(rank === null ? {} : { rank }),
+    };
+}
+/**
+ * Every hit in the box, as GoWay labels, each anchored where it really is.
+ *
+ * Split from the ranking below because the two halves need different things and
+ * one platform cannot do them together. Anchoring is PURE GEOMETRY — no
+ * projection — which is what lets the native fork do it synchronously for every
+ * candidate and then pay for exactly one projection each, instead of one bridge
+ * call per vertex of every street in the box.
+ */
+export function labelCandidatesOf(candidates, tapCoordinate) {
+    const out = [];
+    for (const candidate of candidates) {
+        const label = toLabelFeature(candidate, tapCoordinate, anchorFor(candidate, tapCoordinate));
+        if (label)
+            out.push(label);
+    }
+    return out;
+}
+/**
+ * The label a tap meant, out of everything inside the padded box.
+ *
+ * ## The rule, written down rather than left to the renderer's return order
+ *
+ * 1. **Nearest wins.** Distance in SCREEN PIXELS from the tap to the label's
+ *    own anchor — a point for a POI or a city, and for a street or a river the
+ *    nearest point on the line, which is a real place on that way rather than a
+ *    vertex that may be half a tile away. Pixels, not degrees: a degree is a
+ *    different distance at every latitude, and the user is pointing at pixels.
+ * 2. **A label with no anchor of its own is ranked as if it were at the edge of
+ *    the pad.** A park's name is placed by MapLibre at a pole of inaccessibility
+ *    that does not exist in the tile, so its only honest position is "somewhere
+ *    in this box". Scoring it at zero would make it beat everything; scoring it
+ *    at {@link LABEL_HIT_PAD_PX} makes it lose to anything genuinely nearer and
+ *    win over nothing.
+ * 3. **Then the kind**, most specific first: a POI you can walk into, then the
+ *    street it is on, then water, then the district or city containing all of
+ *    them. A city label spans the screen and is never what a tap meant while
+ *    something smaller is under the finger.
+ * 4. **Then the tiles' own `rank`**, OpenMapTiles' importance ordering.
+ * 5. **Then the id**, so the answer is deterministic rather than dependent on
+ *    the order a renderer happened to return its layers in.
+ */
+export function pickLabelFeature(labels, point, project) {
+    let best = null;
+    let bestScore = null;
+    for (const label of labels) {
+        const projected = label.anchored ? project(label.coordinate) : null;
+        const distance = projected && Number.isFinite(projected.x) && Number.isFinite(projected.y)
+            ? Math.hypot(projected.x - point.x, projected.y - point.y)
+            : // Rule 2: no anchor of its own, so "somewhere in the box".
+                LABEL_HIT_PAD_PX;
+        const score = [
+            distance,
+            KIND_ORDER[label.kind],
+            label.rank ?? Number.MAX_SAFE_INTEGER,
+            label.id,
+        ];
+        if (bestScore === null || compareScores(score, bestScore) < 0) {
+            best = label;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/** Most specific first. See rule 3. */
+const KIND_ORDER = { poi: 0, road: 1, water: 2, area: 3 };
+function compareScores(a, b) {
+    if (a[0] !== b[0])
+        return a[0] - b[0];
+    if (a[1] !== b[1])
+        return a[1] - b[1];
+    if (a[2] !== b[2])
+        return a[2] - b[2];
+    return a[3] < b[3] ? -1 : a[3] > b[3] ? 1 : 0;
+}
+/**
+ * Where a line-drawn label should be considered to BE: the point on the way
+ * nearest the tap.
+ *
+ * Not the nearest VERTEX, which on a long straight avenue can be far from a tap
+ * that landed squarely on the street. The result is a real point on the way,
+ * which is what a pin should sit on and what "directions to this street" needs.
+ *
+ * ## Why this is flat geometry rather than a projection
+ *
+ * The search runs in a local planar frame — longitude scaled by `cos(latitude)`
+ * — instead of in screen pixels. Over one tile at label zooms the difference is
+ * immaterial, and it buys the thing that matters: no projection, so this is
+ * pure, testable, and cheap enough for the NATIVE fork, where every projection
+ * is a bridge call and projecting every vertex of every street in the box would
+ * not be affordable. Both forks therefore anchor identically.
+ *
+ * Returns `null` for anything that is not a usable line, so the caller falls
+ * back to the feature's own point and then to the tap.
+ */
+export function anchorFor(candidate, tap) {
+    const path = candidate.path;
+    if (!path || path.length === 0)
+        return null;
+    // One scale for the whole search, taken at the tap: using each vertex's own
+    // latitude would make the metric inconsistent between segments.
+    const scale = Math.cos((tap.latitude * Math.PI) / 180) || 1;
+    const flat = (at) => ({ x: at.longitude * scale, y: at.latitude });
+    const here = flat(tap);
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let previous = null;
+    for (const vertex of path) {
+        if (!isDrawableCoordinate(vertex)) {
+            previous = null;
+            continue;
+        }
+        if (previous) {
+            const hit = nearestOnSegment(previous, vertex, here, flat);
+            if (hit.distance < bestDistance) {
+                bestDistance = hit.distance;
+                best = hit.at;
+            }
+        }
+        else {
+            const at = flat(vertex);
+            const distance = Math.hypot(at.x - here.x, at.y - here.y);
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                best = vertex;
+            }
+        }
+        previous = vertex;
+    }
+    return best;
+}
+/** The point on one segment nearest the tap, in the local planar frame. */
+function nearestOnSegment(a, b, here, flat) {
+    const pa = flat(a);
+    const pb = flat(b);
+    const dx = pb.x - pa.x;
+    const dy = pb.y - pa.y;
+    const lengthSquared = dx * dx + dy * dy;
+    if (lengthSquared === 0) {
+        return { at: a, distance: Math.hypot(pa.x - here.x, pa.y - here.y) };
+    }
+    const raw = ((here.x - pa.x) * dx + (here.y - pa.y) * dy) / lengthSquared;
+    const t = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+    return {
+        at: {
+            latitude: a.latitude + t * (b.latitude - a.latitude),
+            longitude: a.longitude + t * (b.longitude - a.longitude),
+        },
+        distance: Math.hypot(pa.x + t * dx - here.x, pa.y + t * dy - here.y),
+    };
+}
+/**
+ * The labels currently on screen, deduplicated and capped.
+ *
+ * Both forks report their viewport's labels so the overlay can avoid stacking
+ * its own text on top of one. Two things make
+ * that safe to do on every settled frame:
+ *
+ *  - **Dedup by id.** One POI is drawn by a dot layer and a label layer, and a
+ *    feature that straddles a tile boundary is returned once per tile.
+ *  - **A cap.** A wide, dense viewport is bounded by the collision system to
+ *    tens of labels in practice (44 over central Barcelona at z16, measured),
+ *    but "in practice" is not a bound, and this list crosses into React state.
+ */
+export function collectLabelFeatures(candidates, fallback, limit = 400) {
+    const byId = new Map();
+    for (const candidate of candidates) {
+        if (byId.size >= limit)
+            break;
+        const label = toLabelFeature(candidate, fallback);
+        if (!label || byId.has(label.id))
+            continue;
+        byId.set(label.id, label);
+    }
+    return [...byId.values()];
+}
+/**
+ * Whether two reported label sets are the same set.
+ *
+ * The canvas re-reports on every settled frame, and a fresh array of equal
+ * labels would rebuild every marker on the map for no reason. Ids only: a
+ * label's name and class come from the same tile feature, so an id that has
+ * not changed describes a label that has not changed.
+ */
+export function sameLabelSet(a, b) {
+    if (a === b)
+        return true;
+    if (a.length !== b.length)
+        return false;
+    for (let index = 0; index < a.length; index += 1) {
+        if (a[index].id !== b[index].id)
+            return false;
+    }
+    return true;
+}
+function stringProp(properties, key) {
+    const value = properties[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function numberProp(properties, key) {
+    const value = properties[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * The engine's features, with the engine removed. A feature this cannot
+ * classify is dropped rather than guessed at: the source-layer decides whether
+ * a hit is a POI or a district, and being wrong opens the wrong sheet.
+ */
+export function queriedLabelsOf(features) {
+    const out = [];
+    for (const feature of features) {
+        const properties = feature.properties ?? {};
+        const sourceLayer = sourceLayerOf(feature, properties);
+        if (!sourceLayer || !isLabelSourceLayer(sourceLayer))
+            continue;
+        const geometry = feature.geometry;
+        // A Point becomes a coordinate; a line becomes a PATH, so a street or a
+        // river is anchored at the point on the way the reader pointed at. A
+        // polygon (a park) gets neither: its label is placed at a point only the
+        // engine knows, and the tap stands in for it — the tap is inside it anyway.
+        const coordinate = geometry?.type === 'Point'
+            ? {
+                longitude: geometry.coordinates[0] ?? Number.NaN,
+                latitude: geometry.coordinates[1] ?? Number.NaN,
+            }
+            : null;
+        out.push({
+            featureId: feature.id ?? null,
+            sourceLayer,
+            layerId: feature.layer?.id,
+            properties,
+            coordinate,
+            path: pathOf(geometry),
+        });
+    }
+    return out;
+}
+function sourceLayerOf(feature, properties) {
+    if (typeof feature.sourceLayer === 'string' && feature.sourceLayer)
+        return feature.sourceLayer;
+    for (const key of ['source-layer', 'sourceLayer', 'layer']) {
+        const value = properties[key];
+        if (typeof value === 'string' && value)
+            return value;
+    }
+    return null;
+}
+/**
+ * A line feature's vertices, capped: a motorway clipped to a tile can carry a
+ * great many points and this runs inside a press handler, while the query box
+ * is a few dozen pixels across, so the part of the line the reader could have
+ * meant is a handful of segments.
+ */
+const MAX_PATH_VERTICES = 512;
+function pathOf(geometry) {
+    if (!geometry)
+        return null;
+    const lines = geometry.type === 'LineString'
+        ? [geometry.coordinates]
+        : geometry.type === 'MultiLineString'
+            ? geometry.coordinates
+            : null;
+    if (!lines)
+        return null;
+    const out = [];
+    for (const line of lines) {
+        for (const position of line) {
+            if (out.length >= MAX_PATH_VERTICES)
+                return out;
+            out.push({ longitude: position[0] ?? Number.NaN, latitude: position[1] ?? Number.NaN });
+        }
+    }
+    return out.length > 0 ? out : null;
+}

package/dist/loadedCamera.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A map that has loaded has a settled camera, and the canvas reports it.
+ *
+ * Both forks report the camera through `MapViewProps.onCameraChanged` when
+ * a move SETTLES: MapLibre's `moveend` on the web, `onRegionDidChange` on
+ * native. The camera a map OPENS at is not a move: the web engine sets it with
+ * the constructor's own `jumpTo`, which fires `moveend` inside `new Map()`,
+ * before any listener exists, and MapLibre Native gives no promise either way.
+ * So for a long time nothing reported it, and every caller that needed it got
+ * it by accident or wrote a workaround. The explore list got it by accident:
+ * its first query waits for the first settled camera (`useExplore`), and that
+ * arrived only when something RESIZED the map container (MapLibre's `resize()`
+ * fires a `moveend`). A window that never resized (headless Chromium, and any
+ * browser whose layout settled before the map was built) showed the list's
+ * skeletons until the reader panned.
+ *
+ * The rule, the same for both forks: ONCE PER ENGINE, when it has loaded, its
+ * camera is reported as a settled (`isFinal`) change, `programmatic` because
+ * the app opened the map there and the reader did nothing — so it can never
+ * arm "Search this area". Unless the camera is not settled:
+ *
+ *  - a move is under way (an animation, a gesture): that move's own settle
+ *    reports the camera when it gets there;
+ *  - the camera stands on a frame of a caller-driven animation
+ *    (`MapCameraOptions.transient`): a flyover frame is not a settled camera,
+ *    and the animation's closing, ordinary move reports one;
+ *  - a move started or ended while the camera was being read (native reads it
+ *    asynchronously): the reading may be stale, and that move reports anyway.
+ *
+ * "Once per engine" is what makes the forks agree. The web builds a new engine
+ * for a new style (at the opening camera), so a new style is a new report;
+ * MapLibre Native swaps the style under the same engine and camera, so its
+ * `onDidFinishLoadingStyle` for a new style is not. A retry on native remounts
+ * the engine and starts a new reporter.
+ */
+import type { GeoBoundingBox, MapCameraChange, ResolvedMapViewport } from './types';
+/** What a fork reads off its engine for a camera report. */
+export interface CameraReading {
+    viewport: ResolvedMapViewport;
+    bounds: GeoBoundingBox;
+}
+/** Whether the camera is somewhere it will not stay. */
+export interface CameraMotion {
+    /** A move (animation or gesture) is under way. */
+    moving: boolean;
+    /** The last move to end was a frame of a caller-driven animation. */
+    transient: boolean;
+}
+/** The report a just-loaded map owes its caller, or `null` while the camera is not settled. */
+export declare function loadedCameraChange(reading: CameraReading, motion: CameraMotion): MapCameraChange | null;
+/** One engine's loaded-camera report: fed its moves, asked once it has loaded. */
+export interface LoadedCameraReporter {
+    /** A move began (web `movestart`, native `onRegionWillChange`). */
+    moveStarted(): void;
+    /** A move ended; `transient` when it was a frame of a caller-driven animation. */
+    moveEnded(transient: boolean): void;
+    /**
+     * The engine has loaded. `read` answers its camera, now or later; the
+     * report goes to whatever `listener()` answers then (`null`: no caller).
+     * Only the first call per reporter does anything.
+     */
+    loaded(read: () => CameraReading | null | Promise<CameraReading | null>, listener: () => ((change: MapCameraChange) => void) | null | undefined): void;
+}
+export declare function createLoadedCameraReporter(): LoadedCameraReporter;

package/dist/loadedCamera.js

@@ -0,0 +1,56 @@
+/** The report a just-loaded map owes its caller, or `null` while the camera is not settled. */
+export function loadedCameraChange(reading, motion) {
+    if (motion.moving || motion.transient)
+        return null;
+    return {
+        viewport: reading.viewport,
+        bounds: reading.bounds,
+        source: 'programmatic',
+        isFinal: true,
+    };
+}
+export function createLoadedCameraReporter() {
+    let moving = false;
+    let transient = false;
+    // Bumped by every move boundary, so an asynchronous read can tell that the
+    // camera it is holding may no longer be the one on screen.
+    let generation = 0;
+    let loaded = false;
+    return {
+        moveStarted() {
+            moving = true;
+            generation += 1;
+        },
+        moveEnded(wasTransient) {
+            moving = false;
+            transient = wasTransient;
+            generation += 1;
+        },
+        loaded(read, listener) {
+            if (loaded)
+                return;
+            loaded = true;
+            if (!listener())
+                return;
+            const readAt = generation;
+            const finish = (reading) => {
+                if (!reading || generation !== readAt)
+                    return;
+                const change = loadedCameraChange(reading, { moving, transient });
+                const report = listener();
+                if (change && report)
+                    report(change);
+            };
+            const reading = read();
+            if (reading instanceof Promise) {
+                reading.then(finish, () => {
+                    // An engine that cannot answer has no camera to report; the next
+                    // settled move will.
+                });
+            }
+            else {
+                finish(reading);
+            }
+        },
+    };
+}

package/dist/locationStore.d.ts

@@ -0,0 +1,16 @@
+import type { GeoCoordinate } from './types';
+export type PermissionState = 'unknown' | 'granted' | 'denied';
+type Listener = () => void;
+/** The one permission store; the platform's permission is one per app. */
+export declare const locationPermission: {
+    subscribe(listener: Listener): () => void;
+    getSnapshot(): PermissionState;
+    /** What `useUserLocation` learned by asking. */
+    settle: (next: PermissionState) => void;
+};
+/** The reader's position while a `<UserLocation>` is drawn, in memory only. */
+export declare const userPosition: {
+    subscribe(listener: Listener): () => void;
+    getSnapshot(): GeoCoordinate | null;
+};
+export {};