@mapmap/maps 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -929,6 +929,12 @@ interface RouteLayerOptions {
      * without a design the layer keeps its built-in signal-blue look.
      */
     design?: NavRouteDesign;
+    /**
+     * Colour of the already-travelled part of the line once
+     * {@link RouteLayer.setProgress} is used (the Google-style "vanishing
+     * route line"). Defaults to a dimmed grey.
+     */
+    progressColor?: string;
 }
 /** Draws MapMap routes on a MapLibre map. */
 declare class RouteLayer {
@@ -941,8 +947,14 @@ declare class RouteLayer {
     private readonly sourceId;
     private readonly casingLayerId;
     private readonly lineLayerId;
+    private readonly maneuverSourceId;
+    private readonly maneuverLayerId;
+    private readonly arrowImageId;
     private readonly design;
+    private readonly progressColor;
     private lastRoute;
+    private progress;
+    private maneuver;
     constructor(map: MapMapMap | Map, options?: RouteLayerOptions);
     private readonly handleStyleLoad;
     /**
@@ -963,6 +975,26 @@ declare class RouteLayer {
     draw(route: ParsedRoute): void;
     /** Add-or-update the source and layers for a route on the current style. */
     private install;
+    /**
+     * Sets how much of the route has been travelled, as a fraction in `[0, 1]`
+     * of the line's length. The travelled part dims to `progressColor` (the
+     * "vanishing route line"); `0` restores the untinted line. The value is
+     * remembered across {@link draw} calls and style swaps. Pair with the
+     * guidance module's distance-remaining to derive the fraction.
+     */
+    setProgress(fraction: number): void;
+    /** Applies the current progress fraction to the line layer's gradient. */
+    private applyProgress;
+    /**
+     * Shows (or moves) the upcoming-manoeuvre arrow: a small map-aligned
+     * arrow at `lngLat` rotated to `bearingDeg` (clockwise from north).
+     * Survives style swaps until {@link clearManeuver}.
+     */
+    setManeuver(lngLat: [number, number], bearingDeg: number): void;
+    /** Hides the manoeuvre arrow. */
+    clearManeuver(): void;
+    /** Add-or-update the manoeuvre arrow source/layer for the current style. */
+    private installManeuver;
     /** Remove the route's layers and source from the map. */
     clear(): void;
     /**
@@ -974,6 +1006,29 @@ declare class RouteLayer {
 
 /** Maximum accepted `data:` puck-image payload (matches Studio's upload cap). */
 declare const MAX_PUCK_IMAGE_BYTES: number;
+/**
+ * The signed shortest-arc rotation from `fromDeg` to `toDeg`, in degrees.
+ * Always in `(-180, 180]`, so a heading tween never spins the long way
+ * round the compass (350° -> 10° is +20°, not -340°).
+ */
+declare function shortestArcDeg(fromDeg: number, toDeg: number): number;
+/** Options for {@link PositionPuck}. */
+interface PositionPuckOptions {
+    /**
+     * Animate between fixes instead of snapping (default `true`). Position
+     * lerps linearly and heading tweens along the shortest arc, over a
+     * duration adapted to the observed fix interval (like the
+     * `NavigationCamera` glide, so puck and camera arrive together). Falls
+     * back to instant placement where `requestAnimationFrame` is missing.
+     */
+    interpolate?: boolean;
+    /** Test seam: clock override, defaults to `Date.now`. */
+    now?: () => number;
+    /** Test seam: frame scheduler override, defaults to rAF. */
+    requestFrame?: (callback: () => void) => number;
+    /** Test seam: frame canceller override, defaults to cancelAnimationFrame. */
+    cancelFrame?: (handle: number) => void;
+}
 /** A current-position puck marker for MapMap maps. */
 declare class PositionPuck {
     /** The puck's root DOM element (the Marker element). */
@@ -982,26 +1037,201 @@ declare class PositionPuck {
     private readonly marker;
     private readonly design;
     private added;
+    private readonly interpolate;
+    private readonly now;
+    private readonly requestFrame?;
+    private readonly cancelFrame?;
+    private frameHandle;
+    /** The position/heading currently rendered on the marker. */
+    private rendered;
+    private lastFixAt;
     /**
      * Creates the puck (not yet on the map - it appears on the first
      * {@link setLocation}). The design defaults to the map's
      * `navDesign.puck` when given a `MapMapMap` whose theme carried an
      * `extra.nav` block, then to the built-in blue puck.
      */
-    constructor(map: MapMapMap | Map, design?: NavPuckDesign);
+    constructor(map: MapMapMap | Map, design?: NavPuckDesign, options?: PositionPuckOptions);
     /**
      * Moves the puck (adding it to the map on the first call). `headingDeg`
      * rotates the whole element - arrow or custom image - clockwise from
      * north; omit it to keep the previous heading.
+     *
+     * With interpolation on (the default) every call after the first glides
+     * from the currently rendered position - a fix arriving mid-tween
+     * retargets smoothly rather than jumping.
      */
     setLocation(location: {
         lat: number;
         lon: number;
     }, headingDeg?: number): void;
-    /** Removes the puck from the map. `setLocation` re-adds it. */
+    /** Removes the puck from the map (cancelling any tween). `setLocation` re-adds it. */
     remove(): void;
+    /** Applies a position/heading to the marker immediately. */
+    private render;
+    /** Runs a linear position lerp + shortest-arc heading tween via rAF. */
+    private tween;
+    /** Cancels an in-flight tween, leaving the marker where it rendered last. */
+    private cancelTween;
 }
 
+/**
+ * Auto day/night theme switching from sun position.
+ *
+ * A dependency-free solar calculator (the standard sunrise equation, as
+ * published at https://en.wikipedia.org/wiki/Sunrise_equation, itself a
+ * restatement of the NOAA solar calculation details,
+ * https://gml.noaa.gov/grad/solcalc/calcdetails.html) plus a small
+ * scheduler that flips between light and dark at sunrise/sunset. Nothing
+ * here touches a map: pair {@link ThemeScheduler} with
+ * `MapMapMap.setStyle("light" | "dark")` (or any other callback) in the
+ * app. Territory packages already ship paired light/dark styles, so the
+ * switch works offline too.
+ */
+/** Sun-times result: either both events, or a polar day/night marker. */
+type SunTimes = {
+    sunrise: Date;
+    sunset: Date;
+} | "polarDay" | "polarNight";
+/**
+ * Sunrise and sunset (standard -0.833° horizon: refraction + solar disc)
+ * for the civil day containing `date` (UTC) at `lat`/`lng`, or a polar
+ * marker when the sun never crosses the horizon that day.
+ */
+declare function sunTimes(date: Date, lat: number, lng: number): SunTimes;
+/** The theme the sun dictates at `date` for `lat`/`lng`. */
+declare function resolveTheme(date: Date, lat: number, lng: number): "light" | "dark";
+/** Options for {@link ThemeScheduler}. */
+interface ThemeSchedulerOptions {
+    /** Latitude used for the solar calculation. */
+    lat: number;
+    /** Longitude used for the solar calculation. */
+    lng: number;
+    /** Called (immediately on construction, then at each sunrise) for light. */
+    onLight: () => void;
+    /** Called (immediately on construction, then at each sunset) for dark. */
+    onDark: () => void;
+    /** Test seam: clock override, defaults to `Date.now`. */
+    now?: () => number;
+    /** Test seam: timer override, defaults to `setTimeout`. */
+    setTimeoutFn?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    /** Test seam: timer canceller, defaults to `clearTimeout`. */
+    clearTimeoutFn?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+/**
+ * Applies the sun-appropriate theme now and at every subsequent
+ * sunrise/sunset until {@link dispose}. No OSS map SDK ships this
+ * out of the box; pair with the OS dark-mode signal in the app if the
+ * user's system preference should win instead.
+ */
+declare class ThemeScheduler {
+    private lat;
+    private lng;
+    private readonly onLight;
+    private readonly onDark;
+    private readonly now;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private handle;
+    private applied;
+    private disposed;
+    constructor(options: ThemeSchedulerOptions);
+    /** The theme most recently applied, if any. */
+    get current(): "light" | "dark" | undefined;
+    /** Moves the observer (e.g. a new GPS fix region) and re-evaluates. */
+    setPosition(lat: number, lng: number): void;
+    /** Stops all future flips. */
+    dispose(): void;
+    /** Applies the theme for now and arms the timer for the next boundary. */
+    private evaluate;
+    /** Milliseconds until the next sunrise/sunset (or the polar re-check). */
+    private nextBoundaryDelay;
+}
+
+/**
+ * Runtime label-language switching.
+ *
+ * MapMap tiles carry OpenMapTiles multilingual `name:*` fields
+ * (https://openmaptiles.org/schema/), so a map can switch label language
+ * without new tiles: rewrite each symbol layer's `text-field` to prefer
+ * `name:{language}`. `setMapLanguage(map, "de")` does exactly that for
+ * every layer whose text-field reads name fields (other text — road refs,
+ * house numbers — is left untouched). Pass `null` to restore the compiled
+ * style's default (`name:en` first).
+ *
+ * Server-side, themes can bake a language in with `theme.language`; this
+ * helper is the client-side equivalent for user-facing toggles. For
+ * right-to-left scripts (Arabic, Hebrew) also install MapLibre's RTL text
+ * plugin in the app (`maplibregl.setRTLTextPlugin(...)`) — the SDK does
+ * not fetch remote scripts on your behalf.
+ */
+
+/**
+ * The `text-field` expression for labels in `language` — the requested
+ * language first, the Latin transliteration second, the local name last.
+ * `null` yields the compiled default (`name:en`, then `name`).
+ */
+declare function languageTextField(language: string | null): unknown;
+/**
+ * True when a layer's `text-field` reads `name`/`name:*` properties —
+ * i.e. it is a place/POI/road-name label whose language can switch.
+ * Fields reading other properties (`ref` shields, house numbers) are not.
+ */
+declare function isNameTextField(textField: unknown): boolean;
+/**
+ * Switches every name-label layer of the map's current style to
+ * `language` (`null` restores the style's default). Returns the ids of
+ * the layers it rewrote. Throws on a malformed language tag. Reapply
+ * after `setStyle` — a style swap resets label languages.
+ */
+declare function setMapLanguage(map: MapMapMap | Map, language: string | null): string[];
+
+/**
+ * Probe batch upload - the browser side of opt-in aggregate collection.
+ *
+ * The wasm nav core (`@mapmap/core` `GuidanceSession`) accumulates aggregates
+ * on-device and hands back the exact body to POST via `finishProbeJson()`;
+ * this helper delivers it to the gateway's `POST /v1/probe`, with the same
+ * status handling and retry policy as the mobile SDKs. Aggregates only - the
+ * core is architecturally incapable of emitting a trajectory.
+ *
+ * Consent is the caller's responsibility: only upload for a key whose operator
+ * has set `probe_opt_in`, and - in a browser - only with the user's opt-in
+ * (ePrivacy/PECR) consent. See `docs/PROBE-SDK-INTEGRATION.md`.
+ *
+ * @example
+ * ```ts
+ * const body = session.finishProbeJson(arrived, Date.now());
+ * if (body) void uploadProbeBatch("https://api.mapmap.ai", apiKey, body);
+ * ```
+ */
+/** The outcome of an upload attempt. */
+type ProbeUploadOutcome = "accepted" | "refused" | "notEnabled" | "rejected" | "gaveUp";
+/** Options for {@link uploadProbeBatch}. All optional. */
+interface UploadProbeOptions {
+    /** Injectable fetch (defaults to the global). */
+    fetch?: typeof fetch;
+    /** Total attempts including the first (default 4). */
+    maxAttempts?: number;
+    /** Attempt number → delay before the next try, ms (default `attempt*1000`). */
+    backoffMs?: (attempt: number) => number;
+    /** Injectable delay, for deterministic tests (default `setTimeout`). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Abort signal forwarded to fetch. */
+    signal?: AbortSignal;
+}
+/** The `/v1/probe` endpoint for a gateway origin (trailing slashes trimmed). */
+declare function buildProbeUrl(baseUrl: string): string;
+/**
+ * POST one probe body to `{baseUrl}/v1/probe` with a bearer key. Transient
+ * failures (network or `5xx`) are retried with bounded backoff; permanent ones
+ * (`400`/`403`/`501`) are not. Resolves with the terminal outcome and never
+ * rejects, so a fire-and-forget `void uploadProbeBatch(...)` is safe.
+ *
+ * @param body the string returned by `GuidanceSession.finishProbeJson()`.
+ */
+declare function uploadProbeBatch(baseUrl: string, apiKey: string, body: string, options?: UploadProbeOptions): Promise<ProbeUploadOutcome>;
+
 /** One place to show on the map - a store, depot, branch, POI. */
 interface Place {
     /** Stable unique id, e.g. your store number. */
@@ -1981,4 +2211,4 @@ declare class VoiceGuidance {
     private playEarcon;
 }
 
-export { AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, MapMapMap, type MapMapOptions, type MapMapTheme, NAV_CAMERA_DEFAULTS, type NavBannerDesign, type NavCameraDesign, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerOptions, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type Theme, type ThemeEffects, type TruckParams, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, createMap, createRouteEffect, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, lngLatToMercator, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, resetDiagnostics, runMapDiagnostics, severityProsody, shortestArcDelta, speak, ssmlToText, tessellateRouteRibbon, toLngLat, toPmtilesUrl };
+export { AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, MapMapMap, type MapMapOptions, type MapMapTheme, NAV_CAMERA_DEFAULTS, type NavBannerDesign, type NavCameraDesign, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, type PositionPuckOptions, type ProbeUploadOutcome, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerOptions, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, createMap, createRouteEffect, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, isNameTextField, languageTextField, lngLatToMercator, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, resetDiagnostics, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, uploadProbeBatch };