@konce-pt/map 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konce.pt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+<p align="center">
+  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — Angular component library" width="100%" />
+</p>
+
+# @konce-pt/map
+
+Rdzeń mapy [Koncept UI](https://gitlab.com/konce-pt/koncept-ui): odwzorowanie i arytmetyka
+prostokątów, klastrowanie znaczników, godziny otwarcia, HTML znaczników, formatowanie — oraz
+adaptery silników Leaflet i Google. Czysty TypeScript, **zero zależności runtime**
+(`leaflet` to peer opcjonalny, ładowany dynamicznym `import()`).
+
+Zwykle nie instalujesz go samodzielnie: używają go `@konce-pt/angular/map` i `@konce-pt/react/map`,
+i oba re-eksportują jego API. Sięgnij po niego wprost, gdy liczysz klastry po stronie serwera albo
+podpinasz własny silnik mapowy.
+
+```bash
+npm i @konce-pt/map
+```
+
+```ts
+import { clusterLocations, zoomForBounds, isOpenAt, createLeafletEngine } from '@konce-pt/map';
+
+// Klastrowanie na siatce pikseli — wynik zależy od zoomu, nie od samych współrzędnych.
+clusterLocations(locations, 12, { gridSize: 60 });
+
+// Zoom, przy którym prostokąt mieści się w kontenerze.
+zoomForBounds(bounds, { width: 800, height: 480 });
+
+// Godziny otwarcia razem z zakresami przez północ.
+isOpenAt(hours, new Date());
+
+// Silnik: jedyne miejsce, które zna typy Leafleta.
+const engine = createLeafletEngine({ maxZoom: 19 });
+```
+
+## API
+
+- **Geometria** — `project`, `unproject`, `boundsOf`, `boundsCenter`, `boundsContain`, `padBounds`,
+  `isFittableBounds`, `haversine`, `metersPerPixel`, `zoomForBounds`, `clampLat`, `normalizeLng`
+- **Klastry** — `clusterLocations`, `dominantCategory`, `countByCategory`, `isSplittable`
+- **Znaczniki** — `renderMarkerHtml`, `renderClusterHtml`, `renderUserMarkerHtml`, `colorVarOf`,
+  `contrastVarOf`, `foregroundVarOf`, `clusterTier`
+- **Godziny** — `parseTime`, `formatTime`, `isOpenAt`, `isAlwaysOpen`, `nextChange`, `groupWeek`
+- **Kraje i format** — `KPT_MAP_COUNTRIES`, `countryPreset`, `resolveCountryView`,
+  `formatDistance`, `formatLatLng`, `normalizeUrl`, `prettyUrl`
+- **Silniki** — `createLeafletEngine`, `createGoogleEngine`, `loadGoogleMapsApi`
+- **Typy** — `KptMapEngine`, `KptMapLocation`, `KptMapCategory`, `KptMapPoi` i reszta kontraktu
+
+Pełny opis: [`llms.txt`](./llms.txt) (EN) i [`llms-pl.txt`](./llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/map exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/cluster.d.ts

@@ -0,0 +1,41 @@
+import type { KptMapCluster, KptMapClusterEntry, KptMapLocation } from './types.ts';
+export interface KptClusterOptions {
+    /** Aktualny zoom mapy — decyduje o gęstości siatki. */
+    zoom: number;
+    /** Bok komórki siatki w pikselach ekranu. Domyślnie 60. */
+    gridSize?: number;
+    /** Powyżej tego zoomu grupowanie jest wyłączone. Domyślnie 16. */
+    maxZoom?: number;
+    /** Ile punktów musi trafić do komórki, żeby powstała grupa. Domyślnie 2. */
+    minPoints?: number;
+    /**
+     * Kolejność kategorii — rozstrzyga remis przy wyborze kategorii dominującej.
+     * Bez niej remis rozstrzyga kolejność wystąpienia w danych.
+     */
+    categoryOrder?: readonly string[];
+}
+export declare const KPT_CLUSTER_DEFAULTS: {
+    readonly gridSize: 60;
+    readonly maxZoom: 16;
+    readonly minPoints: 2;
+};
+/**
+ * Zwija bliskie sobie lokalizacje w grupy. Zwraca listę mieszaną: grupy i pojedyncze punkty.
+ *
+ * Środek grupy uśredniamy w przestrzeni pikseli, nie w stopniach. Mercator rozciąga
+ * stopnie tym mocniej, im dalej od równika, więc średnia w stopniach wypada obok
+ * wizualnego środka kropek na ekranie — a to jego ma pilnować znacznik grupy.
+ */
+export declare function clusterLocations<T>(locations: readonly KptMapLocation<T>[], options: KptClusterOptions): KptMapClusterEntry<T>[];
+/**
+ * Najliczniejsza kategoria w grupie. Remis rozstrzyga `categoryOrder`, a bez niej
+ * kolejność pierwszego wystąpienia — w obu wypadkach wynik jest deterministyczny.
+ */
+export declare function dominantCategory<T>(items: readonly KptMapLocation<T>[], categoryOrder?: readonly string[]): string;
+/** Zlicza lokalizacje w rozbiciu na kategorie — licznik obok pozycji legendy. */
+export declare function countByCategory<T>(locations: readonly KptMapLocation<T>[]): Record<string, number>;
+/**
+ * Czy grupa da się rozbić przybliżeniem. Punkty o tej samej współrzędnej zostaną razem
+ * na każdym zoomie — wtedy kliknięcie ma otworzyć listę zamiast zoomować w nieskończoność.
+ */
+export declare function isSplittable<T>(cluster: KptMapCluster<T>): boolean;

package/dist/cluster.js

@@ -0,0 +1,110 @@
+/*
+ * Grupowanie znaczników — siatka w przestrzeni pikseli, O(n), deterministyczna.
+ * Pure TS: ten sam kod obsługuje silnik Leaflet i Google Maps, i przenosi się do Reacta.
+ */
+import { boundsOf, project, unproject } from "./geo.js";
+export const KPT_CLUSTER_DEFAULTS = {
+    gridSize: 60,
+    maxZoom: 16,
+    minPoints: 2,
+};
+/**
+ * Zwija bliskie sobie lokalizacje w grupy. Zwraca listę mieszaną: grupy i pojedyncze punkty.
+ *
+ * Środek grupy uśredniamy w przestrzeni pikseli, nie w stopniach. Mercator rozciąga
+ * stopnie tym mocniej, im dalej od równika, więc średnia w stopniach wypada obok
+ * wizualnego środka kropek na ekranie — a to jego ma pilnować znacznik grupy.
+ */
+export function clusterLocations(locations, options) {
+    const gridSize = options.gridSize ?? KPT_CLUSTER_DEFAULTS.gridSize;
+    const maxZoom = options.maxZoom ?? KPT_CLUSTER_DEFAULTS.maxZoom;
+    const minPoints = Math.max(2, options.minPoints ?? KPT_CLUSTER_DEFAULTS.minPoints);
+    const zoom = options.zoom;
+    if (locations.length === 0)
+        return [];
+    // Powyżej progu pokazujemy wszystko osobno — użytkownik przybliżył się celowo.
+    if (zoom > maxZoom || gridSize <= 0)
+        return [...locations];
+    const cells = new Map();
+    for (const loc of locations) {
+        const p = project(loc.at, zoom);
+        const cellX = Math.floor(p.x / gridSize);
+        const cellY = Math.floor(p.y / gridSize);
+        const key = `${cellX}:${cellY}`;
+        const cell = cells.get(key);
+        if (cell) {
+            cell.items.push(loc);
+            cell.sumX += p.x;
+            cell.sumY += p.y;
+        }
+        else {
+            cells.set(key, { cellX, cellY, items: [loc], sumX: p.x, sumY: p.y });
+        }
+    }
+    const out = [];
+    for (const cell of cells.values()) {
+        if (cell.items.length < minPoints) {
+            out.push(...cell.items);
+            continue;
+        }
+        const center = unproject({ x: cell.sumX / cell.items.length, y: cell.sumY / cell.items.length }, zoom);
+        out.push({
+            id: `c:${zoom}:${cell.cellX}:${cell.cellY}`,
+            at: center,
+            count: cell.items.length,
+            dominantCategoryId: dominantCategory(cell.items, options.categoryOrder),
+            items: cell.items,
+            // Punkty w komórce zawsze istnieją, więc `boundsOf` nie zwróci tu null.
+            bounds: boundsOf(cell.items.map((i) => i.at)),
+        });
+    }
+    return out;
+}
+/**
+ * Najliczniejsza kategoria w grupie. Remis rozstrzyga `categoryOrder`, a bez niej
+ * kolejność pierwszego wystąpienia — w obu wypadkach wynik jest deterministyczny.
+ */
+export function dominantCategory(items, categoryOrder) {
+    const counts = new Map();
+    const firstSeen = new Map();
+    items.forEach((item, index) => {
+        counts.set(item.categoryId, (counts.get(item.categoryId) ?? 0) + 1);
+        if (!firstSeen.has(item.categoryId))
+            firstSeen.set(item.categoryId, index);
+    });
+    let best = items[0].categoryId;
+    let bestCount = -1;
+    for (const [id, count] of counts) {
+        if (count > bestCount) {
+            best = id;
+            bestCount = count;
+            continue;
+        }
+        if (count < bestCount)
+            continue;
+        // Remis — niższy indeks w `categoryOrder` wygrywa, a poza nią wcześniejsze wystąpienie.
+        const rank = (c) => {
+            const i = categoryOrder?.indexOf(c) ?? -1;
+            return i >= 0 ? i : Number.MAX_SAFE_INTEGER;
+        };
+        const byOrder = rank(id) - rank(best);
+        if (byOrder < 0 || (byOrder === 0 && firstSeen.get(id) < firstSeen.get(best)))
+            best = id;
+    }
+    return best;
+}
+/** Zlicza lokalizacje w rozbiciu na kategorie — licznik obok pozycji legendy. */
+export function countByCategory(locations) {
+    const out = {};
+    for (const loc of locations)
+        out[loc.categoryId] = (out[loc.categoryId] ?? 0) + 1;
+    return out;
+}
+/**
+ * Czy grupa da się rozbić przybliżeniem. Punkty o tej samej współrzędnej zostaną razem
+ * na każdym zoomie — wtedy kliknięcie ma otworzyć listę zamiast zoomować w nieskończoność.
+ */
+export function isSplittable(cluster) {
+    const { south, west, north, east } = cluster.bounds;
+    return north - south > 1e-7 || east - west > 1e-7;
+}

package/dist/countries.d.ts

@@ -0,0 +1,27 @@
+import type { KptLatLng, KptMapBounds } from './types.ts';
+export interface KptMapCountryPreset {
+    /** Kod ISO 3166-1 alpha-2 (albo `EU` dla całego kontynentu). */
+    code: string;
+    center: KptLatLng;
+    /** Zoom, przy którym kraj mieści się na typowym kontenerze (~1000×600 px). */
+    zoom: number;
+    bounds: KptMapBounds;
+}
+/** Kod kraju użyty, gdy aplikacja nie poda żadnego. */
+export declare const KPT_MAP_DEFAULT_COUNTRY = "PL";
+/**
+ * Zasięgi lądowe (bez terytoriów zamorskich) zaokrąglone do dwóch miejsc —
+ * to widok startowy, nie granica administracyjna.
+ */
+export declare const KPT_MAP_COUNTRIES: Record<string, KptMapCountryPreset>;
+/** Preset kraju po kodzie (wielkość liter bez znaczenia); `undefined`, gdy nieznany. */
+export declare function countryPreset(code: string): KptMapCountryPreset | undefined;
+/** Kody wszystkich presetów — do listy wyboru w aplikacji. */
+export declare function countryCodes(): string[];
+/**
+ * Widok startowy: preset kraju, a przy nieznanym kodzie preset domyślny.
+ * Zawsze zwraca coś sensownego — mapa nigdy nie startuje na `[0, 0]`.
+ */
+export declare function resolveCountryView(code: string | null | undefined): KptMapCountryPreset;
+/** Środek prostokąta kraju — pomocnicze przy własnych `bounds`. */
+export declare function centerOfBounds(bounds: KptMapBounds): KptLatLng;

package/dist/countries.js

@@ -0,0 +1,50 @@
+/*
+ * Presety widoku bazowego — pure TS. Domyślny kraj to Polska.
+ * Kto potrzebuje kraju spoza listy, podaje `[view]` albo `[bounds]` wprost.
+ */
+import { boundsCenter } from "./geo.js";
+/** Kod kraju użyty, gdy aplikacja nie poda żadnego. */
+export const KPT_MAP_DEFAULT_COUNTRY = 'PL';
+/**
+ * Zasięgi lądowe (bez terytoriów zamorskich) zaokrąglone do dwóch miejsc —
+ * to widok startowy, nie granica administracyjna.
+ */
+export const KPT_MAP_COUNTRIES = {
+    PL: { code: 'PL', center: { lat: 52.07, lng: 19.48 }, zoom: 6, bounds: { south: 49.0, west: 14.07, north: 54.84, east: 24.15 } },
+    DE: { code: 'DE', center: { lat: 51.17, lng: 10.45 }, zoom: 6, bounds: { south: 47.27, west: 5.87, north: 55.06, east: 15.04 } },
+    CZ: { code: 'CZ', center: { lat: 49.82, lng: 15.47 }, zoom: 7, bounds: { south: 48.55, west: 12.09, north: 51.06, east: 18.86 } },
+    SK: { code: 'SK', center: { lat: 48.67, lng: 19.7 }, zoom: 7, bounds: { south: 47.73, west: 16.83, north: 49.61, east: 22.57 } },
+    UA: { code: 'UA', center: { lat: 48.38, lng: 31.17 }, zoom: 6, bounds: { south: 44.39, west: 22.14, north: 52.38, east: 40.23 } },
+    LT: { code: 'LT', center: { lat: 55.17, lng: 23.88 }, zoom: 7, bounds: { south: 53.9, west: 20.94, north: 56.45, east: 26.84 } },
+    LV: { code: 'LV', center: { lat: 56.88, lng: 24.6 }, zoom: 7, bounds: { south: 55.67, west: 20.97, north: 58.09, east: 28.24 } },
+    GB: { code: 'GB', center: { lat: 54.0, lng: -2.9 }, zoom: 5, bounds: { south: 49.9, west: -8.65, north: 60.86, east: 1.77 } },
+    FR: { code: 'FR', center: { lat: 46.6, lng: 2.45 }, zoom: 6, bounds: { south: 41.33, west: -5.14, north: 51.09, east: 9.56 } },
+    ES: { code: 'ES', center: { lat: 40.2, lng: -3.3 }, zoom: 6, bounds: { south: 35.95, west: -9.3, north: 43.79, east: 3.32 } },
+    IT: { code: 'IT', center: { lat: 42.5, lng: 12.5 }, zoom: 6, bounds: { south: 36.65, west: 6.63, north: 47.09, east: 18.52 } },
+    NL: { code: 'NL', center: { lat: 52.2, lng: 5.5 }, zoom: 7, bounds: { south: 50.75, west: 3.36, north: 53.56, east: 7.23 } },
+    BE: { code: 'BE', center: { lat: 50.64, lng: 4.66 }, zoom: 8, bounds: { south: 49.5, west: 2.54, north: 51.5, east: 6.41 } },
+    AT: { code: 'AT', center: { lat: 47.7, lng: 13.35 }, zoom: 7, bounds: { south: 46.37, west: 9.53, north: 49.02, east: 17.16 } },
+    SE: { code: 'SE', center: { lat: 62.2, lng: 16.3 }, zoom: 4, bounds: { south: 55.34, west: 11.11, north: 69.06, east: 24.16 } },
+    NO: { code: 'NO', center: { lat: 64.5, lng: 12.0 }, zoom: 4, bounds: { south: 57.98, west: 4.65, north: 71.19, east: 31.08 } },
+    US: { code: 'US', center: { lat: 39.5, lng: -98.35 }, zoom: 4, bounds: { south: 24.4, west: -125.0, north: 49.38, east: -66.93 } },
+    EU: { code: 'EU', center: { lat: 54.0, lng: 15.0 }, zoom: 4, bounds: { south: 34.8, west: -11.0, north: 71.2, east: 40.2 } },
+};
+/** Preset kraju po kodzie (wielkość liter bez znaczenia); `undefined`, gdy nieznany. */
+export function countryPreset(code) {
+    return KPT_MAP_COUNTRIES[code?.toUpperCase()];
+}
+/** Kody wszystkich presetów — do listy wyboru w aplikacji. */
+export function countryCodes() {
+    return Object.keys(KPT_MAP_COUNTRIES);
+}
+/**
+ * Widok startowy: preset kraju, a przy nieznanym kodzie preset domyślny.
+ * Zawsze zwraca coś sensownego — mapa nigdy nie startuje na `[0, 0]`.
+ */
+export function resolveCountryView(code) {
+    return (code ? countryPreset(code) : undefined) ?? KPT_MAP_COUNTRIES[KPT_MAP_DEFAULT_COUNTRY];
+}
+/** Środek prostokąta kraju — pomocnicze przy własnych `bounds`. */
+export function centerOfBounds(bounds) {
+    return boundsCenter(bounds);
+}

package/dist/engine.d.ts

@@ -0,0 +1,84 @@
+import type { KptLatLng, KptMapBounds, KptMapPoint, KptMapUserPosition } from './types.ts';
+/** Rodzaj silnika — trafia do `data-engine` na hoście, przydatne w testach i stylach. */
+export type KptMapEngineKind = 'leaflet' | 'google';
+export interface KptMapEngineInit {
+    center: KptLatLng;
+    zoom: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** Blokada panningu poza prostokąt. */
+    maxBounds?: KptMapBounds | null;
+    /** Szablon URL kafli, np. `https://tile.openstreetmap.org/{z}/{x}/{y}.png`. */
+    tileUrl: string;
+    /** Tekst atrybucji — wymagany licencyjnie przy OSM. */
+    attribution: string;
+    /** Silnik nie rysuje własnych kontrolek zoomu — robi to warstwa Angulara. */
+    interactive?: boolean;
+}
+/** Znacznik gotowy do narysowania — HTML pochodzi z `marker-html.ts`. */
+export interface KptMapRenderedMarker {
+    /** Stabilne id: `id` lokalizacji albo `id` grupy. */
+    id: string;
+    at: KptLatLng;
+    html: string;
+    /** Rozmiar ikony w pikselach — silnik potrzebuje go do zakotwiczenia. */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Punkt zakotwiczenia względem lewego górnego rogu ikony. */
+    anchor: KptMapPoint;
+    /** Kolejność rysowania — grupy nad pojedynczymi punktami. */
+    zIndex?: number;
+}
+export interface KptMapPointerEvent {
+    at: KptLatLng;
+    /** Piksele względem kontenera mapy. */
+    point: KptMapPoint;
+    /** Zdarzenie źródłowe, gdy trzeba zatrzymać propagację. */
+    originalEvent?: Event;
+}
+export interface KptMapEngineEvents {
+    /** Pan i zoom w toku — używane do przeliczania pozycji popupu. */
+    move: () => void;
+    /** Koniec ruchu — dopiero tu warto emitować `viewChange`. */
+    moveend: () => void;
+    zoomend: () => void;
+    click: (event: KptMapPointerEvent) => void;
+    contextmenu: (event: KptMapPointerEvent) => void;
+    /** Kliknięcie w znacznik; `id` jak w `KptMapRenderedMarker`. */
+    markerclick: (id: string, event: KptMapPointerEvent) => void;
+}
+export interface KptMapEngine {
+    readonly kind: KptMapEngineKind;
+    /** Tworzy mapę w kontenerze. Wywoływane po pierwszym renderze, nigdy na SSR. */
+    init(host: HTMLElement, opts: KptMapEngineInit): Promise<void>;
+    destroy(): void;
+    setView(center: KptLatLng, zoom: number, animate?: boolean): void;
+    fitBounds(bounds: KptMapBounds, paddingPx?: number): void;
+    panBy(offset: KptMapPoint): void;
+    getCenter(): KptLatLng;
+    getZoom(): number;
+    getBounds(): KptMapBounds;
+    getSize(): {
+        width: number;
+        height: number;
+    };
+    /** Współrzędne → piksele WZGLĘDEM kontenera (pozycjonowanie popupu). */
+    project(at: KptLatLng): KptMapPoint;
+    unproject(point: KptMapPoint): KptLatLng;
+    /** Pełna wymiana zestawu znaczników; diff po `id` robi implementacja. */
+    setMarkers(markers: readonly KptMapRenderedMarker[]): void;
+    /** `null` chowa znacznik użytkownika i krąg dokładności. */
+    setUserPosition(position: KptMapUserPosition | null, html: string): void;
+    setTileSource(tileUrl: string, attribution: string): void;
+    setMaxBounds(bounds: KptMapBounds | null): void;
+    /** Kontener zmienił rozmiar — bez tego Leaflet zostawia szare pola. */
+    invalidateSize(): void;
+    on<K extends keyof KptMapEngineEvents>(event: K, handler: KptMapEngineEvents[K]): void;
+}
+/** Fabryka silnika — to ją dostarcza DI, żeby każda mapa miała własną instancję. */
+export type KptMapEngineFactory = () => KptMapEngine;
+/** Domyślne źródło kafli. Do produkcji podstaw własny serwer — patrz llms.txt. */
+export declare const KPT_MAP_DEFAULT_TILE_URL = "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
+export declare const KPT_MAP_DEFAULT_ATTRIBUTION = "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors";

package/dist/engine.js

@@ -0,0 +1,3 @@
+/** Domyślne źródło kafli. Do produkcji podstaw własny serwer — patrz llms.txt. */
+export const KPT_MAP_DEFAULT_TILE_URL = 'https://tile.openstreetmap.org/{z}/{x}/{y}.png';
+export const KPT_MAP_DEFAULT_ATTRIBUTION = '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors';

package/dist/engines/google.engine.d.ts

@@ -0,0 +1,51 @@
+import type { KptMapEngine } from '../engine.ts';
+/**
+ * Namespace `google.maps`. Świadomie `any` — pełne typy przychodzą z opcjonalnego
+ * `@types/google.maps`, a biblioteka nie może od nich zależeć przy kompilacji.
+ */
+export type KptGoogleMapsApi = any;
+export interface KptGoogleOptions {
+    /** Klucz API z Google Cloud. Wymagany. */
+    apiKey: string;
+    /**
+     * Identyfikator stylu mapy z konsoli Google (*Map management → Create Map ID*).
+     *
+     * **Wymagany.** Bez niego nie działa `AdvancedMarkerElement`, a znaczniki tej biblioteki
+     * to gotowy HTML z `marker-html.ts` — starsze `Marker` nie umie go przyjąć.
+     */
+    mapId: string;
+    /** Wersja API. Domyślnie `weekly`. */
+    version?: string;
+    /** Język etykiet na mapie (kod ISO 639-1). Domyślnie język przeglądarki. */
+    language?: string;
+    /** Region wpływający na nazewnictwo i granice sporne (ISO 3166-1 alpha-2). */
+    region?: string;
+    /** Dolny limit zoomu. Domyślnie 2 — niżej świat powtarza się w poziomie. */
+    minZoom?: number;
+    /** Górny limit zoomu. Domyślnie 21. */
+    maxZoom?: number;
+    /** Zoom kółkiem myszy. Domyślnie włączony. */
+    scrollWheelZoom?: boolean;
+}
+/**
+ * Tyle z `KptGoogleOptions`, ile trzeba do wczytania samego API. Bez `mapId` — ten dotyczy
+ * wyglądu mapy, a API potrzebują też usługi, które żadnej mapy nie rysują.
+ */
+export type KptGoogleLoadOptions = Pick<KptGoogleOptions, 'apiKey' | 'version' | 'language' | 'region'>;
+/**
+ * Ładuje Google Maps JavaScript API raz na aplikację. Gdy `google.maps` już istnieje — bo
+ * aplikacja wstawiła skrypt sama albo stoi tu druga mapa — korzystamy z tego, co jest: drugie
+ * wczytanie Google i tak odrzuca, wypisując ostrzeżenie do konsoli.
+ *
+ * Publiczne, bo silnik nie jest jedynym, kto tego API potrzebuje. Geokoder Google **musi**
+ * iść przez SDK, a nie przez REST: web service `/maps/api/geocode/json` odrzuca klucze
+ * z restrykcją `Referer` („API keys with referer restrictions cannot be used with this API"),
+ * a to jedyna restrykcja, jaką da się sensownie nałożyć na klucz leżący w bundlu przeglądarki.
+ * Wywołania z załadowanego SDK autoryzują się tak samo jak sama mapa.
+ *
+ * Adaptera geokodera biblioteka nadal nie dostarcza — tylko drogę do API, którą i tak
+ * otwiera silnikowi. Powody stoją przy `provideKptGoogleMap` i w `llms.txt`.
+ */
+export declare function loadGoogleMapsApi(options: KptGoogleLoadOptions): Promise<KptGoogleMapsApi>;
+/** Fabryka silnika — każda mapa dostaje własną instancję. */
+export declare function createGoogleEngine(options: KptGoogleOptions): KptMapEngine;