@yappkit/front-module-map 0.1.8 → 0.2.1

package/lib/types/main.d.ts

@@ -0,0 +1,121 @@
+import Mapbox from './providers/Mapbox.js';
+import Maplibre from './providers/Maplibre.js';
+import GoogleMaps from './providers/GoogleMaps.js';
+import DeckGL from './providers/DeckGL.js';
+import getAirRoute from './utils/getAirRoute.js';
+import getWaterRoute from './utils/getWaterRoute.js';
+import normalizeRoute from './utils/normalizeRoute.js';
+export declare const utils: {
+    getAirRoute: typeof getAirRoute;
+    getWaterRoute: typeof getWaterRoute;
+    normalizeRoute: typeof normalizeRoute;
+};
+export declare const mapProviders: {
+    mapbox: typeof Mapbox;
+    maplibre: typeof Maplibre;
+    'maplibre-gl': typeof Maplibre;
+    google: typeof GoogleMaps;
+    'google-maps': typeof GoogleMaps;
+    deckgl: typeof DeckGL;
+    'deck-gl': typeof DeckGL;
+};
+export type GoogleMapsConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'google' | 'google-maps';
+    /**
+     * - Google Maps API key. Required: without it the entry is warn+skipped (#255).
+     */
+    apiKey: string;
+    /**
+     * - Google Maps libraries, all loaded in a single loader call (e.g.
+     * 'maps', 'maps3d', 'elevation'); each becomes available through getSDK(name).
+     */
+    libraries?: string[];
+    /**
+     * - Google Maps JS API version channel — Map3D requires 'alpha'
+     * (plus a pre-authorized key).
+     */
+    version?: string;
+};
+export type MapboxConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'mapbox';
+    /**
+     * - Mapbox public access token. Required: without it the entry is warn+skipped (#255).
+     */
+    apiKey: string;
+    /**
+     * - Mapbox REST SDK services to preload; each becomes available through getSDK(name).
+     */
+    services?: Array<'datasets' | 'directions' | 'geocoding' | 'geocodingV6' | 'mapMatching' | 'matrix' | 'optimization' | 'static' | 'styles' | 'tilequery' | 'tilesets' | 'tokens' | 'uploads' | 'isochrone'>;
+};
+export type MaplibreConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'maplibre' | 'maplibre-gl';
+};
+export type DeckGLConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'deckgl' | 'deck-gl';
+};
+export type MapConfig = GoogleMapsConfig | MapboxConfig | MaplibreConfig | DeckGLConfig;
+export type MapsConfig = Record<string, MapConfig>;
+/**
+ * Google Maps provider config (`type: 'google'` / `'google-maps'`).
+ * @typedef {object} GoogleMapsConfig
+ * @property {'google'|'google-maps'} type - Provider discriminant.
+ * @property {string} apiKey - Google Maps API key. Required: without it the entry is warn+skipped (#255).
+ * @property {string[]} [libraries] - Google Maps libraries, all loaded in a single loader call (e.g.
+ * 'maps', 'maps3d', 'elevation'); each becomes available through getSDK(name).
+ * @property {string} [version='weekly'] - Google Maps JS API version channel — Map3D requires 'alpha'
+ * (plus a pre-authorized key).
+ */
+/**
+ * Mapbox provider config (`type: 'mapbox'`), rendering on the mapbox-gl peer.
+ * @typedef {object} MapboxConfig
+ * @property {'mapbox'} type - Provider discriminant.
+ * @property {string} apiKey - Mapbox public access token. Required: without it the entry is warn+skipped (#255).
+ * @property {Array<'datasets'|'directions'|'geocoding'|'geocodingV6'|'mapMatching'|'matrix'|'optimization'|'static'|'styles'|'tilequery'|'tilesets'|'tokens'|'uploads'|'isochrone'>} [services]
+ * - Mapbox REST SDK services to preload; each becomes available through getSDK(name).
+ */
+/**
+ * MapLibre provider config (`type: 'maplibre'` / `'maplibre-gl'`) — the token-less mapbox-gl fork
+ * (#154): no apiKey, and no Mapbox REST services (getSDK refuses them).
+ * @typedef {object} MaplibreConfig
+ * @property {'maplibre'|'maplibre-gl'} type - Provider discriminant.
+ */
+/**
+ * DeckGL provider config (`type: 'deckgl'` / `'deck-gl'`) — no key: composes over the other providers.
+ * @typedef {object} DeckGLConfig
+ * @property {'deckgl'|'deck-gl'} type - Provider discriminant.
+ */
+/**
+ * One entry of the `maps` config: a per-instance provider config, discriminated by `type`.
+ * @typedef {GoogleMapsConfig|MapboxConfig|MaplibreConfig|DeckGLConfig} MapConfig
+ */
+/**
+ * The `maps` config key: instance key → provider config. Each valid entry becomes
+ * `yAppKit.maps.<key>`; a faulty one is warn+skipped (#166/#255/#351).
+ * @typedef {Record<string, MapConfig>} MapsConfig
+ */
+export default class MapModule {
+    /** Builds `yAppKit.maps` — one provider instance per entry of the `maps` config key ({@link MapsConfig}).
+     * @param {object} yAppKit - The yAppKit instance (untyped: @yappkit/front exports no types).
+     * @returns {{onAfterSetup: () => void}} The module's yAppKit lifecycle hooks.
+     */
+    install(yAppKit: object): {
+        onAfterSetup: () => void;
+    };
+}
+/**
+ * Module factory for createYAppKit's `modules` list.
+ * @returns {MapModule} A fresh module instance.
+ */
+export declare const loadMapModule: () => MapModule;

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

@@ -0,0 +1,102 @@
+export type DeckGLMapWrapperOptions = {
+    /**
+     * - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+     */
+    watchOptionsOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+    /**
+     * - Defers map creation: called on mount with the create function instead of creating right away — call `loadMap()` when ready.
+     */
+    onMounted?: (loadMap: () => void) => void;
+};
+export type DeckGLMapOptions = import('@deck.gl/core').DeckProps & DeckGLMapWrapperOptions;
+/**
+ * Wrapper-specific keys of the map options bag — every other key is handed verbatim to the
+ * deck.gl `Deck` constructor (and re-applied through `setProps` on change).
+ * @typedef {object} DeckGLMapWrapperOptions
+ * @property {import('vue').WatchOptions} [watchOptionsOptions] - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+ * @property {(loadMap: () => void) => void} [onMounted] - Defers map creation: called on mount with the create function instead of creating right away — call `loadMap()` when ready.
+ */
+/**
+ * Options accepted by the deckGL `Map` component's `:options` prop and by `createMap`: the
+ * deck.gl `Deck` constructor props plus the wrapper keys.
+ * @typedef {import('@deck.gl/core').DeckProps & DeckGLMapWrapperOptions} DeckGLMapOptions
+ */
+/**
+ * Resolved map wrapper — `createMap`'s resolution and the `Map` component's `@loaded` payload:
+ * the raw `Deck` instance on `.map`, plus reactive watchers taking Vue refs.
+ */
+declare class DeckGLMap {
+    /**
+     * The raw deck.gl instance (e.g. `pickObject`, `redraw`); null until created and after unmount.
+     * @type {import('@deck.gl/core').Deck | null}
+     */
+    map: import('@deck.gl/core').Deck | null;
+    watching: {
+        options: boolean;
+        layers: boolean;
+    };
+    /**
+     * Stop handles of the active watchers, called on unmount.
+     * @type {import('vue').WatchHandle[]}
+     */
+    unwatchFn: import('vue').WatchHandle[];
+    constructor();
+    /**
+     * Keep the map's props in sync with the ref: re-applies its value through `Deck.setProps` on
+     * change (immediate + deep by default). One shot per wrapper: further calls warn and no-op.
+     * @param {import('vue').Ref<DeckGLMapOptions>} opts - Ref to the options bag applied to the map.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchOptions(opts: import('vue').Ref<DeckGLMapOptions>, options?: import('vue').WatchOptions): void;
+    /**
+     * Keep the map's `layers` prop in sync with the ref (immediate, NOT deep: layers are
+     * shallow-compared — swap array/layer identity to update). One shot per wrapper: further calls
+     * warn and no-op.
+     * @param {import('vue').Ref<import('@deck.gl/core').LayersList>} layers - Ref to the deck.gl layers array.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchLayers(layers: import('vue').Ref<import('@deck.gl/core').LayersList>, options?: import('vue').WatchOptions): void;
+}
+export default class DeckGL {
+    deckgl: {
+        Deck: typeof import("@deck.gl/core").Deck;
+    } | null;
+    /**
+     * Memoized component definition (#139), see the `get Map` comment.
+     * @type {import('vue').Component | null}
+     */
+    _MapComponent: import('vue').Component | null;
+    constructor();
+    /**
+     * The deckGL `Map` component. Props: `options` ({@link DeckGLMapOptions}, watched deep) and
+     * `layers` (deck.gl layers, shallow-compared). Emits `loaded` with the {@link DeckGLMap}
+     * wrapper, and `error`. Provides to descendants: `deckGLMap` (ShallowRef<DeckGLMap | null>,
+     * set once loaded), `deckGLPrependLayers` (ShallowRef<LayersList> — layers rendered UNDER the
+     * `layers` prop's, e.g. the google-maps DeckGL3DTileLayer's tiles) and `deckGLAppendVNodeFn`
+     * (Ref<Array<() => VNodeChild>> — vnode factories rendered after the map's div, e.g. a child's
+     * #appendMap credits slot).
+     * @returns {import('vue').Component} The map component definition.
+     */
+    get Map(): import('vue').Component;
+    /**
+     * Lazy-load and memoize the deck.gl `Deck` class (one dynamic import per provider instance).
+     * @returns {Promise<void>}
+     */
+    loadDeckGL(): Promise<void>;
+    /**
+     * Imperative SDK entry — must run during a component's `setup()` (it registers the
+     * onMounted/onUnmounted hooks that create and destroy the map).
+     * @param {import('vue').Ref<HTMLElement | null>} elemRef - Template ref of the element the map renders into (becomes `Deck`'s `parent`).
+     * @param {DeckGLMapOptions} [options] - `Deck` constructor props plus the wrapper keys.
+     * @returns {Promise<DeckGLMap>} Resolves with the map wrapper once created; rejects with `error.code === 'MAP_UNMOUNTED'` when the component unmounts before the map loads (#148).
+     */
+    createMap(elemRef: import('vue').Ref<HTMLElement | null>, options?: DeckGLMapOptions): Promise<DeckGLMap>;
+}
+export {};

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

@@ -0,0 +1,84 @@
+export type DeckGLOverlayWrapperOptions = {
+    /**
+     * - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+     */
+    watchOptionsOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+};
+export type DeckGLOverlayOptions = (import('@deck.gl/mapbox').MapboxOverlayProps | import('@deck.gl/google-maps').GoogleMapsOverlayProps) & DeckGLOverlayWrapperOptions;
+/**
+ * Wrapper-specific keys of the overlay options bag — every other key is handed verbatim to the
+ * provider overlay's constructor (and re-applied through `setProps` on change).
+ * @typedef {object} DeckGLOverlayWrapperOptions
+ * @property {import('vue').WatchOptions} [watchOptionsOptions] - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+ */
+/**
+ * Options accepted by the provider `DeckGLOverlay` components' `:options` prop and by
+ * `setDeckGLOverlay()`: the raw overlay's constructor props (`MapboxOverlayProps` on
+ * mapbox/maplibre maps, `GoogleMapsOverlayProps` on google maps) plus the wrapper keys.
+ * @typedef {(import('@deck.gl/mapbox').MapboxOverlayProps | import('@deck.gl/google-maps').GoogleMapsOverlayProps) & DeckGLOverlayWrapperOptions} DeckGLOverlayOptions
+ */
+/**
+ * Shared deck.gl overlay wiring (#174): the class and the component below used to be duplicated
+ * verbatim in Mapbox.js and GoogleMaps.js — every fix (#151, #156, #165) had to be applied twice.
+ * Providers subclass DeckGLOverlay with their `_detach()` and build their component through
+ * makeDeckGLOverlayComponent with their inject key.
+ */
+export declare class DeckGLOverlay {
+    /**
+     * The raw deck.gl overlay (a @deck.gl/mapbox MapboxOverlay on mapbox/maplibre maps, a
+     * @deck.gl/google-maps GoogleMapsOverlay on google maps), attached by the provider subclass;
+     * null until then and after destroy.
+     * @type {import('@deck.gl/mapbox').MapboxOverlay | import('@deck.gl/google-maps').GoogleMapsOverlay | null}
+     */
+    overlay: import('@deck.gl/mapbox').MapboxOverlay | import('@deck.gl/google-maps').GoogleMapsOverlay | null;
+    watching: {
+        options: boolean;
+        layers: boolean;
+    };
+    unwatchFn: import("vue").WatchHandle[];
+    trackedIn: DeckGLOverlay[] | null;
+    /**
+     * Built by the provider's `setDeckGLOverlay()`, not by consumers directly.
+     * @param {object} config - Wiring handed over by the provider subclass.
+     * @param {import('vue').WatchHandle[]} config.unwatchFn - List collecting the overlay's watcher stop handles (all called and emptied on destroy).
+     * @param {DeckGLOverlay[] | null} [config.trackedIn] - The map wrapper's overlays list this instance is tracked in.
+     */
+    constructor({ unwatchFn, trackedIn }: {
+        unwatchFn: import('vue').WatchHandle[];
+        trackedIn?: DeckGLOverlay[] | null;
+    });
+    /** Stop the watchers, leave the map's tracking list and detach the overlay from the map (#151).
+     * @returns {void}
+     */
+    destroy(): void;
+    /**
+     * Keep the overlay's props in sync with the ref: re-applies its value through `setProps` on
+     * change (immediate + deep by default). One shot per wrapper: further calls warn and no-op.
+     * @param {import('vue').Ref<DeckGLOverlayOptions>} opts - Ref to the options bag applied to the overlay.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchOptions(opts: import('vue').Ref<DeckGLOverlayOptions>, options?: import('vue').WatchOptions): void;
+    /**
+     * Keep the overlay's `layers` prop in sync with the ref (immediate, NOT deep: layers are
+     * shallow-compared — swap array/layer identity to update). One shot per wrapper: further calls
+     * warn and no-op.
+     * @param {import('vue').Ref<import('@deck.gl/core').LayersList>} layers - Ref to the deck.gl layers array.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchLayers(layers: import('vue').Ref<import('@deck.gl/core').LayersList>, options?: import('vue').WatchOptions): void;
+}
+/** Build the provider's DeckGLOverlay component, bound to its injected map key (#174) — it must
+ * nest inside that provider's Map. Props: `options` ({@link DeckGLOverlayOptions}, watched deep)
+ * and `layers` (deck.gl layers, shallow-compared). Emits `loaded` with the {@link DeckGLOverlay}
+ * wrapper, and `error` (#194). Renders nothing itself.
+ * @param {string} mapInjectKey - The provide/inject key of the provider's map ref.
+ * @returns {import('vue').Component} The overlay component definition.
+ */
+export declare const makeDeckGLOverlayComponent: (mapInjectKey: string) => import('vue').Component;

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

@@ -0,0 +1,321 @@
+import { DeckGLOverlay } from './DeckGLOverlay.js';
+declare class GoogleMapsDeckGLOverlay extends DeckGLOverlay {
+    /** setMap(null) only detaches: finalize() is deck.gl's full GL-resource release (#156).
+     * @returns {void}
+     */
+    _detach(): void;
+}
+/**
+ * 2D map wrapper, resolved by createMap and emitted by the Map component's `loaded` event. Its
+ * public surface is ONLY setDeckGLOverlay() and the raw `.map` — the Google 2D map has no
+ * watchOptions/watchLayers (imperative updates go through Google's own setters on `.map`).
+ */
+declare class GoogleMapsMap {
+    /** @type {object|null} The raw google.maps.Map (runtime-loaded API — untyped here). */
+    map: object | null;
+    /** @type {import('vue').WatchStopHandle[]} Stopped by createMap's unmount (#148/#165). */
+    unwatchFn: import('vue').WatchStopHandle[];
+    /** @type {GoogleMapsDeckGLOverlay[]} Overlays attached via setDeckGLOverlay. */
+    overlays: GoogleMapsDeckGLOverlay[];
+    constructor();
+    /** Create a deck.gl GoogleMapsOverlay (lazy-imported) and attach it to the map.
+     * @param {import('@deck.gl/google-maps').GoogleMapsOverlayProps} [options] - GoogleMapsOverlay constructor props (deck props plus `interleaved`).
+     * @returns {Promise<GoogleMapsDeckGLOverlay>} The overlay wrapper: watchOptions/watchLayers/destroy.
+     */
+    setDeckGLOverlay(options?: import('@deck.gl/google-maps').GoogleMapsOverlayProps): Promise<GoogleMapsDeckGLOverlay>;
+}
+export type GoogleMapsMap3DLayer = {
+    /**
+     * - Unique layer id: written to the element's `name` attribute and used by the by-id diff.
+     */
+    id: string;
+    /**
+     * - The layer's DOM element (a gmp-* Maps 3D element), inserted into the <gmp-map-3d> at its array position (array order = z-order).
+     */
+    element: Element;
+};
+/**
+ * A Map3D layer entry (the Map3D component's `layers` items / watchLayers input): a pre-built
+ * layer element keyed for the by-id diff (#195).
+ * @typedef {object} GoogleMapsMap3DLayer
+ * @property {string} id - Unique layer id: written to the element's `name` attribute and used by the by-id diff.
+ * @property {Element} element - The layer's DOM element (a gmp-* Maps 3D element), inserted into the <gmp-map-3d> at its array position (array order = z-order).
+ */
+/**
+ * 3D map wrapper, resolved by createMap3D and emitted by the Map3D component's `loaded` event,
+ * around the runtime-loaded <gmp-map-3d> Map3DElement.
+ */
+declare class GoogleMapsMap3D {
+    /** @type {HTMLElement|null} The <gmp-map-3d> Map3DElement — a DOM element whose Maps-specific API is runtime-loaded and untyped here. */
+    map: HTMLElement | null;
+    watching: {
+        options: boolean;
+        layers: boolean;
+    };
+    /** @type {import('vue').WatchStopHandle[]} Stopped by createMap3D's unmount (#148/#165). */
+    unwatchFn: import('vue').WatchStopHandle[];
+    constructor();
+    /** Collect the element's Web IDL attribute names: enumerable ACCESSOR descriptors on its prototype.
+     * @param {object} obj - The element (or nested element state) to inspect.
+     * @returns {string[]} The accessor property names.
+     */
+    _getSetters(obj: object): string[];
+    /** Snapshot the element's Web IDL attributes into a plain options object.
+     * @param {object} obj - The element (or nested element state) to snapshot.
+     * @param {WeakSet<object>} [seen] - Guards accessor cycles across the recursion.
+     * @returns {Record<string, any>} Attribute name → current value (nested element state recursed into plain objects).
+     */
+    _getOptions(obj: object, seen?: WeakSet<object>): Record<string, any>;
+    /** Assign a bag of Map3DElement attributes — the imperative sibling of watchOptions.
+     * @param {Record<string, any>} [props] - Attribute name → value, assigned onto the element (runtime-loaded API — untyped here).
+     * @returns {void}
+     */
+    setProps(props?: Record<string, any>): void;
+    /** Snapshot the map's current Web IDL attributes — the imperative sibling of getProps-less reads.
+     * @returns {Record<string, any>} Attribute name → current value.
+     */
+    getProps(): Record<string, any>;
+    /** Get a layer element added under the <gmp-map-3d> by its id (the element's `name` attribute).
+     * @param {string} id - The layer id.
+     * @returns {Element|null} The layer's element, or null when absent.
+     */
+    getLayer(id: string): Element | null;
+    /** Keep the Map3DElement in sync with a reactive options object (per-key JSON diff). One
+     * watcher per wrapper: further calls warn and return.
+     * @param {import('vue').Ref<Record<string, any>>} opts - Reactive options bag; every changed key is assigned onto the element.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true, deep: true }`.
+     * @returns {void}
+     */
+    watchOptions(opts: import('vue').Ref<Record<string, any>>, options?: import('vue').WatchOptions): void;
+    /** Keep the <gmp-map-3d> children in sync with a reactive layers array: by-id diff (#195),
+     * array order = z-order via insertBefore. One watcher per wrapper: further calls warn and return.
+     * @param {import('vue').Ref<GoogleMapsMap3DLayer[]>} layers - Reactive layers; shallow-compared — swap array/layer identity (shallowRef) to update.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true }`.
+     * @returns {void}
+     */
+    watchLayers(layers: import('vue').Ref<GoogleMapsMap3DLayer[]>, options?: import('vue').WatchOptions): void;
+}
+export type GoogleMapsMountHook = {
+    /**
+     * - Defers map creation: called at component mount with `loadMap` instead of an immediate load — the map exists only once you invoke it.
+     */
+    onMounted?: (loadMap: () => void) => void;
+};
+export type GoogleMapsMapOptions = GoogleMapsMountHook & Record<string, any>;
+export type GoogleMapsWatcherOptions = {
+    /**
+     * - Vue watch options for the internal options watcher.
+     */
+    watchOptionsOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watch options for the internal layers watcher.
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+};
+export type GoogleMapsMap3DOptions = GoogleMapsMountHook & GoogleMapsWatcherOptions & Record<string, any>;
+export type GoogleMapsMapProps = {
+    /**
+     * - Passed once to google.maps.Map — NOT reactive (an update logs an error; drive the loaded wrapper's `.map` through Google's own setters instead).
+     */
+    options?: GoogleMapsMapOptions;
+};
+export type GoogleMapsMap3DProps = {
+    /**
+     * - Watched (per-key JSON diff) and assigned onto the Map3DElement.
+     */
+    options?: GoogleMapsMap3DOptions;
+    /**
+     * - Watched with a by-id diff (#195); shallow-compared — swap array/layer identity (shallowRef) to update.
+     */
+    layers?: GoogleMapsMap3DLayer[];
+};
+export type GoogleMapsDeckGLOverlayProps = {
+    /**
+     * - GoogleMapsOverlay props, watched deep → overlay.setProps().
+     */
+    options?: import('@deck.gl/google-maps').GoogleMapsOverlayProps & GoogleMapsWatcherOptions;
+    /**
+     * - deck.gl layers, watched → setProps({ layers }); shallow-compared — swap identity to update.
+     */
+    layers?: import('@deck.gl/core').LayersList;
+};
+export type GoogleMapsDeckGL3DTileLayerProps = {
+    /**
+     * - Tile3DLayer prop overrides (over the Google 3D Tiles defaults) — NOT reactive: replace the component to change them.
+     */
+    options?: Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>;
+};
+export type GoogleMapsMapComponent = import('vue').DefineSetupFnComponent<GoogleMapsMapProps, {
+    loaded: (map: GoogleMapsMap) => void;
+    error: (error: Error) => void;
+}>;
+export type GoogleMapsMap3DComponent = import('vue').DefineSetupFnComponent<GoogleMapsMap3DProps, {
+    loaded: (map: GoogleMapsMap3D) => void;
+    error: (error: Error) => void;
+}>;
+export type GoogleMapsDeckGLOverlayComponent = import('vue').DefineSetupFnComponent<GoogleMapsDeckGLOverlayProps, {
+    loaded: (overlay: GoogleMapsDeckGLOverlay) => void;
+    error: (error: Error) => void;
+}>;
+export type GoogleMapsDeckGL3DTileLayerComponent = import('vue').DefineSetupFnComponent<GoogleMapsDeckGL3DTileLayerProps, {
+    error: (error: Error) => void;
+}, import('vue').SlotsType<{
+    appendMap?: {
+        credits: string;
+    };
+}>>;
+/**
+ * Module-side mount hook recognised by createMap/createMap3D (every other option key is forwarded
+ * to Google untouched).
+ * @typedef {object} GoogleMapsMountHook
+ * @property {(loadMap: () => void) => void} [onMounted] - Defers map creation: called at component mount with `loadMap` instead of an immediate load — the map exists only once you invoke it.
+ */
+/**
+ * Options for createMap / the 2D Map component's `options` prop: google.maps.MapOptions
+ * (runtime-loaded API — untyped here: center/zoom/mapId/…) plus {@link GoogleMapsMountHook}.
+ * @typedef {GoogleMapsMountHook & Record<string, any>} GoogleMapsMapOptions
+ */
+/**
+ * Per-watcher tuning read by the Map3D and DeckGLOverlay components from their `options` prop.
+ * @typedef {object} GoogleMapsWatcherOptions
+ * @property {import('vue').WatchOptions} [watchOptionsOptions] - Vue watch options for the internal options watcher.
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watch options for the internal layers watcher.
+ */
+/**
+ * Options for createMap3D / the Map3D component's `options` prop: Map3DElement attributes
+ * (runtime-loaded API — untyped here: center/range/tilt/…) plus the module-side keys.
+ * @typedef {GoogleMapsMountHook & GoogleMapsWatcherOptions & Record<string, any>} GoogleMapsMap3DOptions
+ */
+/**
+ * Props of the 2D Map component. NO `layers` prop: deck.gl layers on a Google 2D map go through
+ * DeckGLOverlay only.
+ * @typedef {object} GoogleMapsMapProps
+ * @property {GoogleMapsMapOptions} [options] - Passed once to google.maps.Map — NOT reactive (an update logs an error; drive the loaded wrapper's `.map` through Google's own setters instead).
+ */
+/**
+ * Props of the Map3D component.
+ * @typedef {object} GoogleMapsMap3DProps
+ * @property {GoogleMapsMap3DOptions} [options] - Watched (per-key JSON diff) and assigned onto the Map3DElement.
+ * @property {GoogleMapsMap3DLayer[]} [layers] - Watched with a by-id diff (#195); shallow-compared — swap array/layer identity (shallowRef) to update.
+ */
+/**
+ * Props of the DeckGLOverlay component (nests inside the 2D Map).
+ * @typedef {object} GoogleMapsDeckGLOverlayProps
+ * @property {import('@deck.gl/google-maps').GoogleMapsOverlayProps & GoogleMapsWatcherOptions} [options] - GoogleMapsOverlay props, watched deep → overlay.setProps().
+ * @property {import('@deck.gl/core').LayersList} [layers] - deck.gl layers, watched → setProps({ layers }); shallow-compared — swap identity to update.
+ */
+/**
+ * Props of the DeckGL3DTileLayer component (nests inside the deckGL provider's Map).
+ * @typedef {object} GoogleMapsDeckGL3DTileLayerProps
+ * @property {Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>} [options] - Tile3DLayer prop overrides (over the Google 3D Tiles defaults) — NOT reactive: replace the component to change them.
+ */
+/**
+ * The 2D Map component type: `loaded` emits the {@link GoogleMapsMap} wrapper, `error` every load failure (#148/#378).
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsMapProps, { loaded: (map: GoogleMapsMap) => void, error: (error: Error) => void }>} GoogleMapsMapComponent
+ */
+/**
+ * The Map3D component type: `loaded` emits the {@link GoogleMapsMap3D} wrapper, `error` every load failure (#148/#378).
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsMap3DProps, { loaded: (map: GoogleMapsMap3D) => void, error: (error: Error) => void }>} GoogleMapsMap3DComponent
+ */
+/**
+ * The DeckGLOverlay component type: `loaded` emits the {@link GoogleMapsDeckGLOverlay} wrapper, `error` every load failure (#194).
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsDeckGLOverlayProps, { loaded: (overlay: GoogleMapsDeckGLOverlay) => void, error: (error: Error) => void }>} GoogleMapsDeckGLOverlayComponent
+ */
+/**
+ * The DeckGL3DTileLayer component type: `error` on load failure (#194); the #appendMap slot
+ * receives `{ credits }` — Google's 3D Tiles attribution, which must stay visible.
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsDeckGL3DTileLayerProps, { error: (error: Error) => void }, import('vue').SlotsType<{ appendMap?: { credits: string } }>>} GoogleMapsDeckGL3DTileLayerComponent
+ */
+/**
+ * Google Maps provider: one instance per `maps` config entry with `type: 'google'`/`'google-maps'`,
+ * exposed as `yAppKit.maps.<key>` — Vue components (Map, Map3D, DeckGLOverlay, DeckGL3DTileLayer)
+ * plus the imperative SDK (getSDK, createMap, createMap3D, createDeckGL3DTileLayer).
+ */
+export default class GoogleMaps {
+    apiKey: string;
+    libraries: string[];
+    version: string;
+    _mapsApiConfigured: boolean;
+    authFailed: boolean;
+    /** @type {Record<string, object>} Loaded google library namespaces by name (runtime-loaded API — untyped here), filled by getSDK. */
+    sdk: Record<string, object>;
+    deckgl: {
+        Tile3DLayer: typeof import("@deck.gl/geo-layers").Tile3DLayer;
+    } | null;
+    /** @type {GoogleMapsMapComponent|null} 2D Map memo. */
+    _MapComponent: GoogleMapsMapComponent | null;
+    /** @type {GoogleMapsMap3DComponent|null} Map3D memo. */
+    _Map3DComponent: GoogleMapsMap3DComponent | null;
+    /** @type {GoogleMapsDeckGLOverlayComponent|null} DeckGLOverlay memo. */
+    _DeckGLOverlayComponent: GoogleMapsDeckGLOverlayComponent | null;
+    /** @type {GoogleMapsDeckGL3DTileLayerComponent|null} DeckGL3DTileLayer memo. */
+    _DeckGL3DTileLayerComponent: GoogleMapsDeckGL3DTileLayerComponent | null;
+    /** @type {Promise<Record<string, object>>} The initial libraries preload: resolves with the `sdk` map, rejects like getSDK(). */
+    ready: Promise<Record<string, object>>;
+    /** Validates the config and starts the SDK preload (`this.ready`, #149).
+     * @param {import('../main.js').GoogleMapsConfig} mapConfig - The provider's `maps` config entry (apiKey/libraries/version; `type` is consumed by the module loader).
+     */
+    constructor(mapConfig: import('../main.js').GoogleMapsConfig);
+    /** The 2D Map component (memoized per provider instance, #139): `options` prop only — nest
+     * DeckGLOverlay inside for deck.gl layers; `@loaded` emits the {@link GoogleMapsMap} wrapper.
+     * @returns {GoogleMapsMapComponent} The memoized component definition.
+     */
+    get Map(): GoogleMapsMapComponent;
+    /** The Map3D component (memoized, #139): `options` + `layers` props, both watched; `@loaded`
+     * emits the {@link GoogleMapsMap3D} wrapper.
+     * @returns {GoogleMapsMap3DComponent} The memoized component definition.
+     */
+    get Map3D(): GoogleMapsMap3DComponent;
+    /** The DeckGLOverlay component (memoized, #139; shared wiring #174): nests inside the 2D Map;
+     * `options`/`layers` props, `@loaded` emits the {@link GoogleMapsDeckGLOverlay} wrapper.
+     * @returns {GoogleMapsDeckGLOverlayComponent} The memoized component definition.
+     */
+    get DeckGLOverlay(): GoogleMapsDeckGLOverlayComponent;
+    /** The DeckGL3DTileLayer component (memoized, #139): nests inside the deckGL provider's Map and
+     * prepends the Google 3D Tiles layer; its #appendMap slot receives `{ credits }` (attribution
+     * that must stay visible).
+     * @returns {GoogleMapsDeckGL3DTileLayerComponent} The memoized component definition.
+     */
+    get DeckGL3DTileLayer(): GoogleMapsDeckGL3DTileLayerComponent;
+    /** Configure the js-api-loader once (page-level, #188) and import every wanted library into
+     * `this.sdk` (already-loaded ones are reused).
+     * @param {object} [options] - Load options.
+     * @param {string[]} [options.libraries] - Extra libraries to load on top of the config's.
+     * @returns {Promise<void>} Resolves once every wanted library is in `this.sdk`.
+     */
+    loadGoogleMapsSDK({ libraries }?: {
+        libraries?: string[];
+    }): Promise<void>;
+    getSDK(options: string): Promise<object>;
+    getSDK(options?: {
+        libraries?: string[];
+    }): Promise<Record<string, object>>;
+    /** Create a google.maps.Map into `elemRef` and resolve with its wrapper. Must run during a
+     * component's setup(): it registers onMounted/onUnmounted (teardown, #148/#156).
+     * @param {import('vue').Ref<HTMLElement|null>} elemRef - Template ref of the map's container element.
+     * @param {GoogleMapsMapOptions} [options] - google.maps.MapOptions plus the module's mount hook.
+     * @returns {Promise<GoogleMapsMap>} The 2D wrapper (setDeckGLOverlay/.map); rejects on unmount-before-load (error.code 'MAP_UNMOUNTED'), SDK failure, or page-level auth failure (#378).
+     */
+    createMap(elemRef: import('vue').Ref<HTMLElement | null>, options?: GoogleMapsMapOptions): Promise<GoogleMapsMap>;
+    /** Create a <gmp-map-3d> Map3DElement into `elemRef` and resolve with its wrapper. Must run
+     * during a component's setup(): it registers onMounted/onUnmounted (teardown, #148/#156).
+     * Requires the 'maps3d' library — `version: 'alpha'` plus a pre-authorized key.
+     * @param {import('vue').Ref<HTMLElement|null>} elemRef - Template ref of the map's container element.
+     * @param {GoogleMapsMap3DOptions} [options] - Map3DElement attributes plus the module-side keys.
+     * @returns {Promise<GoogleMapsMap3D>} The 3D wrapper (watchOptions/watchLayers/setProps/…); rejects on unmount-before-load (error.code 'MAP_UNMOUNTED'), SDK failure, or page-level auth failure (#378).
+     */
+    createMap3D(elemRef: import('vue').Ref<HTMLElement | null>, options?: GoogleMapsMap3DOptions): Promise<GoogleMapsMap3D>;
+    /** Lazy-import Tile3DLayer into `this.deckgl`.
+     * @returns {Promise<void>} Resolves once Tile3DLayer is available.
+     */
+    loadDeckGL(): Promise<void>;
+    /** Build a Tile3DLayer preconfigured for Google's photorealistic 3D Tiles (keyed with this
+     * provider's apiKey), wiring the tileset copyrights into `credits` — Google's terms require
+     * showing them (the DeckGL3DTileLayer component's #appendMap slot).
+     * @param {import('vue').Ref<string>} credits - Written on every tileset traversal with the '; '-joined copyrights (#328).
+     * @param {Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>} [options] - Tile3DLayer prop overrides; a consumer `onTilesetLoad` is composed after the credits wiring, not clobbering it (#391).
+     * @returns {Promise<import('@deck.gl/geo-layers').Tile3DLayer>} The layer, for the deckGL provider Map's `layers`.
+     */
+    createDeckGL3DTileLayer(credits: import('vue').Ref<string>, options?: Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>): Promise<import('@deck.gl/geo-layers').Tile3DLayer>;
+}
+export {};