@yappkit/front-module-map 0.1.8 → 0.2.1

package/lib/types/providers/Mapbox.d.ts

@@ -0,0 +1,210 @@
+import { DeckGLOverlay } from './DeckGLOverlay.js';
+/** Shared wiring lives in DeckGLOverlay.js (#174); only the detach mode is provider-specific. */
+declare class MapboxDeckGLOverlay extends DeckGLOverlay {
+    /** @type {import('mapbox-gl').Map|import('maplibre-gl').Map|null} The host map; released by destroy (#284). */
+    map: import('mapbox-gl').Map | import('maplibre-gl').Map | null;
+    /** Wire the shared overlay state and keep the host map for `_detach` (#151).
+     * @param {object} args - Constructor args.
+     * @param {import('vue').WatchStopHandle[]} args.unwatchFn - The overlay's own watcher stop handles (#151).
+     * @param {import('mapbox-gl').Map|import('maplibre-gl').Map} args.map - The host map (maplibre-gl's on the Maplibre provider).
+     * @param {MapboxDeckGLOverlay[]} [args.trackedIn] - The owning map wrapper's overlays list (#156).
+     */
+    constructor({ unwatchFn, map, trackedIn }: {
+        unwatchFn: import('vue').WatchStopHandle[];
+        map: import('mapbox-gl').Map | import('maplibre-gl').Map;
+        trackedIn?: MapboxDeckGLOverlay[];
+    });
+    /** mapbox-gl's removeControl triggers MapboxOverlay's onRemove, which finalizes the
+     * underlying deck instance (#151).
+     * @returns {void}
+     */
+    _detach(): void;
+    /** Release the provider-specific Map reference after the base cleanup: a destroyed wrapper still
+     * held by the consumer (setDeckGLOverlay return, @loaded payload) retained the whole mapbox-gl
+     * Map graph — the base destroy only clears what IT owns (#212 covered the list→wrapper side). (#284)
+     * @returns {void}
+     */
+    destroy(): void;
+}
+export type MapSourceDef = (Parameters<import('mapbox-gl').Map['addSource']>[1] | Parameters<import('maplibre-gl').Map['addSource']>[1]) & {
+    id: string;
+};
+export type MapLayerDef = Parameters<import('mapbox-gl').Map['addLayer']>[0] | Parameters<import('maplibre-gl').Map['addLayer']>[0];
+/**
+ * One entry of the `sources` array/prop: whatever the underlying map's `addSource` accepts (a source
+ * specification — GeoJSON, vector, raster… — or a custom source), plus the `id` the wrapper diffs by (#143).
+ * @typedef {(Parameters<import('mapbox-gl').Map['addSource']>[1]|Parameters<import('maplibre-gl').Map['addSource']>[1]) & { id: string }} MapSourceDef
+ */
+/**
+ * One entry of the `layers` array/prop: whatever the underlying map's `addLayer` accepts — a layer
+ * specification (whose `source` may be an inline source object, see the #9135 workaround in
+ * watchLayers) or a custom layer.
+ * @typedef {Parameters<import('mapbox-gl').Map['addLayer']>[0]|Parameters<import('maplibre-gl').Map['addLayer']>[0]} MapLayerDef
+ */
+/**
+ * The resolved map wrapper: the raw map on `.map`, the reactive watchers, and setDeckGLOverlay.
+ * Shared by the Mapbox and Maplibre providers (createMap is not overridden, #154).
+ */
+declare class MapboxMap {
+    /** @type {import('mapbox-gl').Map|import('maplibre-gl').Map|null} The raw underlying map (maplibre-gl's on the Maplibre provider), set by createMap. */
+    map: import('mapbox-gl').Map | import('maplibre-gl').Map | null;
+    watching: {
+        sources: boolean;
+        layers: boolean;
+    };
+    /** @type {import('vue').WatchStopHandle[]} Stop handles of every watcher owned by the map, run on unmount. */
+    unwatchFn: import('vue').WatchStopHandle[];
+    /** @type {MapboxDeckGLOverlay[]} */
+    overlays: MapboxDeckGLOverlay[];
+    /** @type {WeakMap<object, string>} */
+    _propsIds: WeakMap<object, string>;
+    constructor();
+    /** Signature of a source's non-data props, cached per object identity (#158).
+     * @param {MapSourceDef} source - A source object from the `sources` prop.
+     * @returns {string} The JSON signature of the source without its `data`.
+     */
+    _propsIdOf(source: MapSourceDef): string;
+    /** Keep the map's sources in sync with the reactive array, diffed by source id (#143): sources are
+     * shallow-compared — swap array/object identity to update — except a data-only change (same
+     * propsId), applied in place through setData.
+     * @template {MapSourceDef[]|undefined} T
+     * @param {import('vue').Ref<T>} sources - The reactive sources array.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true }`.
+     * @returns {void}
+     */
+    watchSources<T extends MapSourceDef[] | undefined>(sources: import('vue').Ref<T>, options?: import('vue').WatchOptions): void;
+    /** Keep the map's layers in sync with the reactive array, diffed by layer id (#144): layers are
+     * shallow-compared — swap array/layer identity to update; added/changed layers land at their array
+     * position in the z-order (#301).
+     * @template {MapLayerDef[]|undefined} T
+     * @param {import('vue').Ref<T>} layers - The reactive layers array.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true }`.
+     * @returns {void}
+     */
+    watchLayers<T extends MapLayerDef[] | undefined>(layers: import('vue').Ref<T>, options?: import('vue').WatchOptions): void;
+    /** Attach a deck.gl overlay (lazy-loaded MapboxOverlay) to the map.
+     * @param {import('@deck.gl/mapbox').MapboxOverlayProps} [options] - The overlay's constructor props (deck.gl layers, interleaved, …).
+     * @returns {Promise<MapboxDeckGLOverlay>} The overlay wrapper: its own watchOptions/watchLayers/destroy.
+     */
+    setDeckGLOverlay(options?: import('@deck.gl/mapbox').MapboxOverlayProps): Promise<MapboxDeckGLOverlay>;
+}
+export type MapboxServiceName = NonNullable<import('../main.js').MapboxConfig['services']>[number];
+export type MapboxMapExtraOptions = {
+    /**
+     * - Take over map creation timing: receives the
+     * `loadMap` thunk and decides when to call it.
+     */
+    onMounted?: (loadMap: () => void) => void;
+    /**
+     * - Vue watch options for the component's sources watcher.
+     */
+    watchSourcesOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watch options for the component's layers watcher.
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+};
+export type MapboxMapOptions = Omit<import('mapbox-gl').MapOptions, 'container'> & MapboxMapExtraOptions;
+/**
+ * A Mapbox REST SDK service name (the keys of `servicesLoader`).
+ * @typedef {NonNullable<import('../main.js').MapboxConfig['services']>[number]} MapboxServiceName
+ */
+/**
+ * Wrapper-specific options riding along the map constructor options.
+ * @typedef {object} MapboxMapExtraOptions
+ * @property {(loadMap: () => void) => void} [onMounted] - Take over map creation timing: receives the
+ * `loadMap` thunk and decides when to call it.
+ * @property {import('vue').WatchOptions} [watchSourcesOptions] - Vue watch options for the component's sources watcher.
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watch options for the component's layers watcher.
+ */
+/**
+ * Options of the Mapbox `Map` component / `createMap`: mapbox-gl's `MapOptions` minus `container`
+ * (the component's element / `elemRef` provides it) — `accessToken` defaults to the config `apiKey` —
+ * plus the wrapper extras.
+ * @typedef {Omit<import('mapbox-gl').MapOptions, 'container'> & MapboxMapExtraOptions} MapboxMapOptions
+ */
+/** Mapbox provider (`type: 'mapbox'`): the `Map`/`DeckGLOverlay` components, `createMap` and the REST SDK. */
+export default class Mapbox {
+    /** @type {string|undefined} The configured access token (undefined on the token-less Maplibre subclass, #154). */
+    apiKey: string | undefined;
+    /** @type {MapboxServiceName[]} The REST SDK services to (pre)load. */
+    services: MapboxServiceName[];
+    /** @type {Partial<Record<MapboxServiceName, object>>} The loaded REST service clients by name (plain objects: the mapbox SDK ships no types). */
+    sdk: Partial<Record<MapboxServiceName, object>>;
+    /** @type {typeof import('mapbox-gl/esm')|typeof import('maplibre-gl')|null} The lazily loaded gl namespace (maplibre-gl's on the Maplibre subclass). */
+    mapboxgl: typeof import('mapbox-gl/esm') | typeof import('maplibre-gl') | null;
+    /** @type {import('vue').Component|null} */
+    _MapComponent: import('vue').Component | null;
+    /** @type {import('vue').Component|null} */
+    _DeckGLOverlayComponent: import('vue').Component | null;
+    /** @type {Promise<object>} The SDK preload: resolves with the `sdk` registry, rejects like getSDK(). */
+    ready: Promise<object>;
+    /** Subclasses can opt out of the token requirement (#154): MapLibre works without any key.
+     * @returns {boolean} Whether the constructor requires an apiKey.
+     */
+    get requiresApiKey(): boolean;
+    /** Build the provider from its `maps` config entry and kick off the SDK preload (#149).
+     * @param {import('../main.js').MapboxConfig|import('../main.js').MaplibreConfig} mapConfig - The
+     * `maps.<key>` config entry (the token-less MaplibreConfig on the Maplibre subclass, #154).
+     */
+    constructor(mapConfig: import('../main.js').MapboxConfig | import('../main.js').MaplibreConfig);
+    /** The map Vue component: `:options` ({@link MapboxMapOptions}), `:layers` ({@link MapLayerDef}
+     * array), `:sources` ({@link MapSourceDef} array); emits `loaded` with the {@link MapboxMap}
+     * wrapper, and `error`.
+     * @returns {import('vue').Component} The memoized component definition (#139).
+     */
+    get Map(): import('vue').Component;
+    /** The deck.gl overlay Vue component (nests inside `Map`): `:options`, `:layers`; emits `loaded`
+     * with the overlay wrapper, and `error`.
+     * @returns {import('vue').Component} The memoized component definition (#139).
+     */
+    get DeckGLOverlay(): import('vue').Component;
+    /** Lazy-load the gl namespace (and its css) into `this.mapboxgl`, once.
+     * @returns {Promise<void>}
+     */
+    loadMapbox(): Promise<void>;
+    /** The lazy REST SDK service loaders — one dynamic import per service, so only the requested
+     * services are fetched; its keys are the valid {@link MapboxServiceName}s.
+     * @returns {Record<MapboxServiceName, () => Promise<{ default: (client: object) => object }>>} Service
+     * name → loader of the service module, whose `default` builds the client-bound service.
+     */
+    get servicesLoader(): Record<MapboxServiceName, () => Promise<{
+        default: (client: object) => object;
+    }>>;
+    /** Build the token-bound SDK client and load the wanted services into `this.sdk` (#150).
+     * @param {object} [options] - Options.
+     * @param {MapboxServiceName[]} [options.services] - Services to load on top of the configured ones.
+     * @returns {Promise<void>}
+     */
+    loadMapboxSDK({ services }?: {
+        services?: MapboxServiceName[];
+    }): Promise<void>;
+    /** Load and return Mapbox REST SDK services (the config `services` plus the requested ones).
+     * @param {MapboxServiceName|{services?: MapboxServiceName[]}} [options] - A single service name, or
+     * `{ services }` to load several at once.
+     * @returns {Promise<object>} The named service client for a string argument, the whole `sdk`
+     * registry otherwise (plain objects: the mapbox SDK ships no types).
+     * @throws {Error} When a service name is unknown (#150) or its client is not loaded.
+     */
+    getSDK(options?: MapboxServiceName | {
+        services?: MapboxServiceName[];
+    }): Promise<object>;
+    /** Map constructor options, overridable per subclass (maplibre-gl has no accessToken option, #154).
+     * @param {HTMLElement} container - The map container element.
+     * @param {MapboxMapOptions} options - Consumer-provided map options.
+     * @returns {import('mapbox-gl').MapOptions} The options passed to `new mapboxgl.Map()`.
+     */
+    _getMapOptions(container: HTMLElement, options: MapboxMapOptions): import('mapbox-gl').MapOptions;
+    /** Create the map imperatively (must run in a component's setup(): the lifecycle hooks drive it):
+     * resolves the wrapper once the map emits 'load', rejects on ANY failure (#148/#228) — with
+     * `error.code === 'MAP_UNMOUNTED'` when the component unmounted first — and tears the map, its
+     * watchers and its overlays down on unmount.
+     * @template {HTMLElement|null|undefined} TEl
+     * @param {import('vue').Ref<TEl>} elemRef - Template ref to the map's container element.
+     * @param {MapboxMapOptions} [options] - Map constructor options plus the wrapper extras
+     * (maplibre-gl's own options on the Maplibre subclass).
+     * @returns {Promise<MapboxMap>} The map wrapper.
+     */
+    createMap<TEl extends HTMLElement | null | undefined>(elemRef: import('vue').Ref<TEl>, options?: MapboxMapOptions): Promise<MapboxMap>;
+}
+export {};

package/lib/types/providers/Maplibre.d.ts

@@ -0,0 +1,37 @@
+import Mapbox from './Mapbox.js';
+export type MaplibreMapOptions = Omit<import('maplibre-gl').MapOptions, 'container'> & import('./Mapbox.js').MapboxMapExtraOptions;
+/**
+ * Options of the Maplibre `Map` component / `createMap`: maplibre-gl's `MapOptions` minus `container`
+ * (the component's element / `elemRef` provides it), plus the wrapper extras shared with Mapbox.
+ * @typedef {Omit<import('maplibre-gl').MapOptions, 'container'> & import('./Mapbox.js').MapboxMapExtraOptions} MaplibreMapOptions
+ */
+/**
+ * Maplibre provider (`type: 'maplibre'`/`'maplibre-gl'`): the token-less mapbox-gl fork — same
+ * Map/DeckGLOverlay/createMap surface as Mapbox, minus the REST SDK (#154).
+ */
+export default class Maplibre extends Mapbox {
+    /** MapLibre is the token-less mapbox-gl fork (#154).
+     * @returns {boolean} Always false: no apiKey needed.
+     */
+    get requiresApiKey(): boolean;
+    /** Lazy-load the maplibre-gl namespace (and its css) into `this.mapboxgl`, once, pinning its web
+     * worker — the whole story below.
+     * @returns {Promise<void>}
+     */
+    loadMapbox(): Promise<void>;
+    /** No Mapbox REST SDK on maplibre (#154): the constructor preload resolves to an empty sdk,
+     * and requesting a service (argument or configured `services`) is a consumer error.
+     * @param {string|{services?: string[]}} [options] - Service name or `{ services }` object, like Mapbox's getSDK.
+     * @returns {Promise<object>} The (empty) sdk registry.
+     * @throws {Error} When a service is requested.
+     */
+    getSDK(options?: string | {
+        services?: string[];
+    }): Promise<object>;
+    /** maplibre-gl has no accessToken option (#154): container + consumer options only.
+     * @param {HTMLElement} container - The map container element.
+     * @param {MaplibreMapOptions} options - Consumer-provided map options.
+     * @returns {import('maplibre-gl').MapOptions} The options passed to `new maplibregl.Map()`.
+     */
+    _getMapOptions(container: HTMLElement, options: MaplibreMapOptions): import('maplibre-gl').MapOptions;
+}

package/lib/types/searoute/searoute.d.ts

@@ -0,0 +1,45 @@
+export type SeaRouteFeature = {
+    /**
+     * - GeoJSON object type.
+     */
+    type: 'Feature';
+    /**
+     * - The `[lng, lat]` network
+     * path, from origin's snap to destination's snap.
+     */
+    geometry: {
+        type: 'LineString';
+        coordinates: number[][];
+    };
+    /**
+     * - The route
+     * length, expressed in `units`.
+     */
+    properties: {
+        units: 'nm' | import('@turf/turf').Units;
+        length: number;
+    };
+};
+/**
+ * The returned route: the GeoJSON LineString Feature built by turf's lineString() over the snapped
+ * network path, with the measured length stamped on `properties` (#138, same contract as the air
+ * twin, #257).
+ * @typedef {object} SeaRouteFeature
+ * @property {'Feature'} type - GeoJSON object type.
+ * @property {{type: 'LineString', coordinates: number[][]}} geometry - The `[lng, lat]` network
+ * path, from origin's snap to destination's snap.
+ * @property {{units: 'nm'|import('@turf/turf').Units, length: number}} properties - The route
+ * length, expressed in `units`.
+ */
+/**
+ * Shortest sea route between two points, each snapped to the Marnet network first, via
+ * geojson-path-finder (weight() bridges the anti-meridian edges).
+ * @param {import('@turf/turf').Coord} origin - Start point: a turf point() Feature, a bare Point
+ * geometry, or a `[lng, lat]` position.
+ * @param {import('@turf/turf').Coord} destination - End point, same accepted shapes.
+ * @param {'nm'|import('@turf/turf').Units} [units='nm'] - Unit of `properties.length`; 'nm' is the
+ * module's alias for turf's 'nauticalmiles' (#138).
+ * @returns {SeaRouteFeature|null} The snapped route — null when no path exists (reachable on valid
+ * inputs, the network is fragmented, #141).
+ */
+export default function searoute(origin: import('@turf/turf').Coord, destination: import('@turf/turf').Coord, units?: 'nm' | import('@turf/turf').Units): SeaRouteFeature | null;

package/lib/types/utils/getAirRoute.d.ts

@@ -0,0 +1,71 @@
+export type AirRouteOptions = {
+    /**
+     * - Start position, `[lng, lat]`.
+     */
+    origin: number[];
+    /**
+     * - End position, `[lng, lat]`.
+     */
+    destination: number[];
+    /**
+     * - Number of arc segments (the geometry holds `step` interpolated
+     * positions plus the destination, before dedupe); a non-integer or non-positive value falls back
+     * to 100 (#157).
+     */
+    step?: number;
+    /**
+     * - Unit of `properties.length`; 'nm' is
+     * the module's alias for turf's 'nauticalmiles' (#138).
+     */
+    units?: 'nm' | import('@turf/turf').Units;
+};
+export type AirRouteFeature = {
+    /**
+     * - GeoJSON object type.
+     */
+    type: 'Feature';
+    /**
+     * - The arc's `[lng, lat]`
+     * positions; longitudes are unfolded by normalizeRoute and may run past ±180 (#159).
+     */
+    geometry: {
+        type: 'LineString';
+        coordinates: number[][];
+    };
+    /**
+     * - The route
+     * length, expressed in `units`.
+     */
+    properties: {
+        units: 'nm' | import('@turf/turf').Units;
+        length: number;
+    };
+};
+/**
+ * Arguments of getAirRoute.
+ * @typedef {object} AirRouteOptions
+ * @property {number[]} origin - Start position, `[lng, lat]`.
+ * @property {number[]} destination - End position, `[lng, lat]`.
+ * @property {number} [step=100] - Number of arc segments (the geometry holds `step` interpolated
+ * positions plus the destination, before dedupe); a non-integer or non-positive value falls back
+ * to 100 (#157).
+ * @property {'nm'|import('@turf/turf').Units} [units='nm'] - Unit of `properties.length`; 'nm' is
+ * the module's alias for turf's 'nauticalmiles' (#138).
+ */
+/**
+ * The returned route: the GeoJSON LineString Feature built by turf's lineString(), with the
+ * measured length stamped on `properties` (#257).
+ * @typedef {object} AirRouteFeature
+ * @property {'Feature'} type - GeoJSON object type.
+ * @property {{type: 'LineString', coordinates: number[][]}} geometry - The arc's `[lng, lat]`
+ * positions; longitudes are unfolded by normalizeRoute and may run past ±180 (#159).
+ * @property {{units: 'nm'|import('@turf/turf').Units, length: number}} properties - The route
+ * length, expressed in `units`.
+ */
+/**
+ * Great-circle ("air") route between origin and destination: a geodesic arc interpolated with
+ * turf's along(), then unfolded across the anti-meridian and measured on the final geometry.
+ * @param {AirRouteOptions} options - Route endpoints and arc options.
+ * @returns {AirRouteFeature} The arc as a GeoJSON LineString Feature.
+ */
+export default function getAirRoute({ origin, destination, step, units }: AirRouteOptions): AirRouteFeature;

package/lib/types/utils/getWaterRoute.d.ts

@@ -0,0 +1,40 @@
+export type WaterRouteOptions = {
+    /**
+     * - Start position, `[lng, lat]`.
+     */
+    origin: number[];
+    /**
+     * - End position, `[lng, lat]`.
+     */
+    destination: number[];
+    /**
+     * - Prepend/append the REAL origin/destination to the
+     * snapped network path (boundary legs), and recompute `properties.length` over the extended
+     * geometry (#159).
+     */
+    includeBoundaries?: boolean;
+    /**
+     * - Unit of `properties.length`; 'nm' is
+     * the module's alias for turf's 'nauticalmiles' (#138).
+     */
+    units?: 'nm' | import('@turf/turf').Units;
+};
+/**
+ * Arguments of getWaterRoute.
+ * @typedef {object} WaterRouteOptions
+ * @property {number[]} origin - Start position, `[lng, lat]`.
+ * @property {number[]} destination - End position, `[lng, lat]`.
+ * @property {boolean} [includeBoundaries=false] - Prepend/append the REAL origin/destination to the
+ * snapped network path (boundary legs), and recompute `properties.length` over the extended
+ * geometry (#159).
+ * @property {'nm'|import('@turf/turf').Units} [units='nm'] - Unit of `properties.length`; 'nm' is
+ * the module's alias for turf's 'nauticalmiles' (#138).
+ */
+/**
+ * Sea ("water") route between origin and destination over the Marnet network, computed by the
+ * dynamically-imported searoute engine, then unfolded across the anti-meridian.
+ * @param {WaterRouteOptions} options - Route endpoints and options.
+ * @returns {Promise<import('../searoute/searoute.js').SeaRouteFeature|null>} The route as a GeoJSON
+ * LineString Feature (`properties.units`/`length` set) — null when no path exists (#141).
+ */
+export default function getWaterRoute({ origin, destination, includeBoundaries, units }: WaterRouteOptions): Promise<import('../searoute/searoute.js').SeaRouteFeature | null>;

package/lib/types/utils/normalizeRoute.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unfold a route's longitudes across anti-meridian crossings: whenever two consecutive longitudes
+ * jump by more than 180°, shift by ±360 so the line never wraps — the unfolded longitudes may run
+ * past ±180 (turf's haversine handles them, #159). Drops any altitude member on the way.
+ * @param {number[][]} coords - The route positions, `[lng, lat]` first.
+ * @returns {Array<[number, number]>} The unfolded `[lng, lat]` pairs, consecutive duplicates removed.
+ */
+export default function normalizeRoute(coords: number[][]): Array<[number, number]>;