@konce-pt/react 0.8.0

package/dist/map/map.js

@@ -0,0 +1,425 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { KPT_MAP_DEFAULT_ATTRIBUTION, KPT_MAP_DEFAULT_TILE_URL, boundsOf, clusterLocations, countByCategory, haversine, isCluster, isSplittable, renderClusterHtml, renderMarkerHtml, renderUserMarkerHtml, resolveCountryView, } from '@konce-pt/map';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { cn } from "../internal/cn.js";
+import { useControllableState } from "../internal/use-controllable-state.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
+import { getKptIcon } from "../icon/icon-registry.js";
+import { KptDialog } from "../dialog/dialog.js";
+import { KptMapCreateDialog } from "./map-create-dialog.js";
+import { KptMapLegend } from "./map-legend.js";
+import { KptMapSearch } from "./map-search.js";
+/** Rozmiary ikon w pikselach — silnik potrzebuje ich do zakotwiczenia znacznika. */
+const MARKER_SIZE = { width: 32, height: 42 };
+const DOT_SIZE = { width: 24, height: 24 };
+const CLUSTER_SIZE = { width: 44, height: 44 };
+/** Ile miejsca zostawić wokół zasięgu przy `fitBounds`. */
+const FIT_PADDING = 48;
+/** Zapas na strzałkę i cień popupu przy sprawdzaniu, czy mieści się w kontenerze. */
+const POPUP_MARGIN = 16;
+/**
+ * Identyfikator tymczasowej pinezki wyszukiwarki. Nie należy do wpisów, więc kliknięcie
+ * w nią niczego nie otwiera.
+ */
+const SEARCH_MARKER_ID = 'kpt-map:search';
+/** Brak silnika to najczęstsza pomyłka przy pierwszym użyciu — komunikat niesie instrukcję. */
+const NO_ENGINE_ERROR = 'KptMap: brak silnika mapy. Podaj fabrykę przez prop `engine` — ' +
+    '`engine={() => createLeafletEngine()}` albo ' +
+    '`engine={() => createGoogleEngine({ apiKey, mapId })}` z `@konce-pt/react/map`.';
+/**
+ * Mapa z konfigurowalnymi znacznikami: kategorie z kolorem i ikoną, grupowanie z licznikiem,
+ * popup szczegółów, legenda, wyszukiwarka adresów i dodawanie lokalizacji prawym przyciskiem.
+ *
+ * Silnik (Leaflet albo Google) przychodzi propem `engine` z `@konce-pt/map` — ta sama warstwa,
+ * na której stoi port Angulara. Leaflet ładuje się dynamicznym `import()`, więc aplikacja bez
+ * mapy go nie pobiera; wymaga też arkusza `leaflet/dist/leaflet.css`.
+ *
+ * @example
+ * <KptMap
+ *   engine={() => createLeafletEngine()}
+ *   locations={locations}
+ *   categories={categories}
+ *   renderPopup={({ location, data }) => <strong>{location.title}</strong>}
+ * />
+ */
+export function KptMap({ locations, categories, country = 'PL', view = null, bounds = null, restrictToCountry = false, cluster = true, clusterOptions, clusterColorBy = 'none', legend = true, legendCounts = true, hiddenCategories, defaultHiddenCategories = [], onHiddenCategoriesChange, showUserLocation = false, followUser = false, geolocation = null, allowCreate = false, search = false, searchPlaceholder = '', searchOptions, searchZoom = 16, searchMarker = true, geocoder = null, popupLayout = 'plain', distanceFrom = null, height = '480px', tileUrl = null, attribution = null, engine, renderPopup, renderCreateForm, onLocationClick, onClusterClick, onLocationCreate, onSearchSelect, onViewChange, onUserPositionChange, onUserLocationError, locale: localeOverride, dictionary, className, style, ...rest }) {
+    const { t } = useKptMessages({ locale: localeOverride, dictionary });
+    const canvasRef = useRef(null);
+    const popupRef = useRef(null);
+    const engineRef = useRef(null);
+    /**
+     * Łańcuch montażu i demontażu tego kontenera. Silnik mapowy oznacza element jako zajęty
+     * na czas życia mapy, a w trybie ścisłym React montuje efekt dwa razy pod rząd — drugi
+     * montaż musi więc poczekać, aż pierwszy skończy sprzątać.
+     */
+    const mountChain = useRef(Promise.resolve());
+    const [engineKind, setEngineKind] = useState(null);
+    const [ready, setReady] = useState(false);
+    /** Zoom trzymamy w stanie, bo od niego zależy wynik grupowania. */
+    const [zoom, setZoom] = useState(6);
+    /** Rośnie przy każdym ruchu mapy — wymusza przeliczenie pozycji nakładek. */
+    const [viewportTick, setViewportTick] = useState(0);
+    const [popup, setPopup] = useState(null);
+    const [contextTarget, setContextTarget] = useState(null);
+    const [createFor, setCreateFor] = useState(null);
+    const [createOpen, setCreateOpen] = useState(false);
+    const [userPosition, setUserPosition] = useState(null);
+    const [locationBlocked, setLocationBlocked] = useState(false);
+    /** Ostatni wybrany wynik wyszukiwania — źródło tymczasowej pinezki. */
+    const [searchPin, setSearchPin] = useState(null);
+    const [hidden, setHidden] = useControllableState({
+        value: hiddenCategories,
+        defaultValue: defaultHiddenCategories,
+        onChange: onHiddenCategoriesChange,
+    });
+    const categoryById = useMemo(() => new Map(categories.map((category) => [category.id, category])), [categories]);
+    /** Lokalizacje po odfiltrowaniu kategorii ukrytych w legendzie. */
+    const visibleLocations = useMemo(() => {
+        const hiddenSet = new Set(hidden);
+        return hiddenSet.size === 0 ? locations : locations.filter((l) => !hiddenSet.has(l.categoryId));
+    }, [locations, hidden]);
+    const counts = useMemo(() => (legendCounts ? countByCategory(locations) : null), [legendCounts, locations]);
+    /** Wynik grupowania dla aktualnego zoomu — grupy i punkty pojedyncze. */
+    const entries = useMemo(() => {
+        if (!cluster)
+            return [...visibleLocations];
+        return clusterLocations(visibleLocations, {
+            ...clusterOptions,
+            zoom,
+            categoryOrder: categories.map((category) => category.id),
+        });
+    }, [cluster, visibleLocations, clusterOptions, zoom, categories]);
+    const restrictBounds = useCallback(() => (restrictToCountry ? (bounds ?? resolveCountryView(country).bounds) : null), [restrictToCountry, bounds, country]);
+    /** Znaczniki gotowe dla silnika. HTML powstaje w rdzeniu, poza Reactem. */
+    const markers = useMemo(() => {
+        const selectedId = popup?.location.id ?? null;
+        const rendered = entries.map((entry) => {
+            if (isCluster(entry)) {
+                const category = clusterColorBy === 'dominant' ? categoryById.get(entry.dominantCategoryId) : undefined;
+                return {
+                    id: entry.id,
+                    at: entry.at,
+                    html: renderClusterHtml({
+                        count: entry.count,
+                        color: category?.color ?? 'primary',
+                        label: t('map.cluster', { count: entry.count }),
+                    }),
+                    size: CLUSTER_SIZE,
+                    anchor: { x: CLUSTER_SIZE.width / 2, y: CLUSTER_SIZE.height / 2 },
+                    // Grupy nad pojedynczymi punktami — licznik ma być czytelny.
+                    zIndex: 500,
+                };
+            }
+            const category = categoryById.get(entry.categoryId);
+            const shape = category?.shape ?? 'pin';
+            const size = shape === 'pin' ? MARKER_SIZE : DOT_SIZE;
+            return {
+                id: entry.id,
+                at: entry.at,
+                html: renderMarkerHtml({
+                    shape,
+                    color: category?.color ?? 'muted',
+                    iconSvgInner: category?.icon ? getKptIcon(category.icon) : undefined,
+                    label: entry.title,
+                    selected: entry.id === selectedId,
+                }),
+                size,
+                // Pinezka kotwiczy się czubkiem, kropka i kwadrat środkiem.
+                anchor: shape === 'pin' ? { x: size.width / 2, y: size.height } : { x: size.width / 2, y: size.height / 2 },
+                zIndex: entry.id === selectedId ? 400 : 0,
+            };
+        });
+        // Pinezka wyniku wyszukiwania idzie tą samą drogą co reszta znaczników, więc przesuwa się
+        // z mapą klatka po klatce i nie wymaga niczego od silnika.
+        const pin = searchMarker ? searchPin : null;
+        if (pin) {
+            rendered.push({
+                id: SEARCH_MARKER_ID,
+                at: pin.at,
+                html: renderMarkerHtml({
+                    shape: 'pin',
+                    color: 'info',
+                    iconSvgInner: getKptIcon('map-pin'),
+                    label: pin.label,
+                }),
+                size: MARKER_SIZE,
+                anchor: { x: MARKER_SIZE.width / 2, y: MARKER_SIZE.height },
+                // Nad grupami (500) — to na nią użytkownik właśnie kazał mapie polecieć.
+                zIndex: 600,
+            });
+        }
+        return rendered;
+    }, [entries, popup, clusterColorBy, categoryById, t, searchMarker, searchPin]);
+    /**
+     * Przesuwa mapę tak, żeby świeżo otwarty popup zmieścił się w kontenerze. Wymiarów popupu
+     * nie znamy przed renderem, więc mierzymy go po dograniu ramki.
+     */
+    const autoPanToPopup = useCallback((state) => {
+        requestAnimationFrame(() => {
+            const map = engineRef.current;
+            const element = popupRef.current;
+            if (!map || !element)
+                return;
+            const anchor = map.project(state.location.at);
+            const size = map.getSize();
+            const rect = element.getBoundingClientRect();
+            // Popup kotwiczy się nad znacznikiem i jest wyśrodkowany w poziomie.
+            const top = anchor.y - rect.height - POPUP_MARGIN;
+            const left = anchor.x - rect.width / 2;
+            const right = anchor.x + rect.width / 2;
+            let dx = 0;
+            let dy = 0;
+            if (top < POPUP_MARGIN)
+                dy = top - POPUP_MARGIN;
+            if (left < POPUP_MARGIN)
+                dx = left - POPUP_MARGIN;
+            else if (right > size.width - POPUP_MARGIN)
+                dx = right - (size.width - POPUP_MARGIN);
+            if (dx !== 0 || dy !== 0)
+                map.panBy({ x: dx, y: dy });
+        });
+    }, []);
+    /*
+     * Zdarzenia silnika czytają najświeższe dane przez referencję: silnik montujemy raz,
+     * a jego callbacki żyją dłużej niż render, w którym powstały.
+     */
+    const latest = useRef({ entries, allowCreate, popup, contextTarget, onLocationClick, onClusterClick, onViewChange });
+    latest.current = { entries, allowCreate, popup, contextTarget, onLocationClick, onClusterClick, onViewChange };
+    const emitViewChange = useCallback(() => {
+        const map = engineRef.current;
+        if (!map)
+            return;
+        setZoom(map.getZoom());
+        latest.current.onViewChange?.({ center: map.getCenter(), zoom: map.getZoom(), bounds: map.getBounds() });
+    }, []);
+    const onMarkerClick = useCallback((id) => {
+        setContextTarget(null);
+        const entry = latest.current.entries.find((candidate) => candidate.id === id);
+        if (!entry)
+            return;
+        if (isCluster(entry)) {
+            latest.current.onClusterClick?.(entry);
+            // Grupa punktów o tej samej współrzędnej nie da się rozbić zoomem — pokaż listę.
+            if (isSplittable(entry)) {
+                engineRef.current?.fitBounds(entry.bounds, FIT_PADDING);
+                return;
+            }
+            const state = { location: entry.items[0], group: entry };
+            setPopup(state);
+            autoPanToPopup(state);
+            return;
+        }
+        const state = { location: entry, group: null };
+        setPopup(state);
+        autoPanToPopup(state);
+        latest.current.onLocationClick?.(entry);
+    }, [autoPanToPopup]);
+    /*
+     * Montaż silnika — raz na życie komponentu.
+     *
+     * Sprzątanie czeka na zakończenie `init()`: w trybie ścisłym React montuje efekt dwa razy,
+     * a silnik mapowy oznacza kontener jako zajęty już przy pierwszym wywołaniu. Zniszczenie
+     * „w locie", przed rozwiązaniem obietnicy, zostawiłoby oznaczony kontener i drugi montaż
+     * kończyłby się błędem „Map container is already initialized".
+     */
+    useEffect(() => {
+        let disposed = false;
+        const map = engine();
+        engineRef.current = map;
+        setEngineKind(map.kind);
+        const preset = resolveCountryView(country);
+        const canvas = canvasRef.current;
+        if (!canvas)
+            throw new Error(NO_ENGINE_ERROR);
+        mountChain.current = mountChain.current
+            .then(() => map.init(canvas, {
+            center: view?.center ?? preset.center,
+            zoom: view?.zoom ?? preset.zoom,
+            maxBounds: restrictBounds(),
+            tileUrl: tileUrl ?? KPT_MAP_DEFAULT_TILE_URL,
+            attribution: attribution ?? KPT_MAP_DEFAULT_ATTRIBUTION,
+        }))
+            .then(() => {
+            if (disposed)
+                return;
+            // Jawny zasięg wygrywa nad środkiem i zoomem: dopiero teraz znamy rozmiar kontenera.
+            if (bounds && !view)
+                map.fitBounds(bounds, FIT_PADDING);
+            // Silnik emituje `move` co klatkę przeciągania. Bez nakładek nikt tej pozycji nie czyta.
+            map.on('move', () => {
+                if (latest.current.popup || latest.current.contextTarget)
+                    setViewportTick((tick) => tick + 1);
+            });
+            map.on('moveend', () => emitViewChange());
+            map.on('zoomend', () => setZoom(map.getZoom()));
+            map.on('click', () => {
+                setPopup(null);
+                setContextTarget(null);
+                setSearchPin(null);
+            });
+            map.on('contextmenu', (event) => {
+                if (!latest.current.allowCreate)
+                    return;
+                setPopup(null);
+                setContextTarget({ at: event.at, point: event.point });
+            });
+            map.on('markerclick', (id) => onMarkerClick(id));
+            setZoom(map.getZoom());
+            setReady(true);
+            emitViewChange();
+        });
+        return () => {
+            disposed = true;
+            engineRef.current = null;
+            setReady(false);
+            // Zniszczenie dopinamy do łańcucha: dopiero po `init()`, bo inaczej `destroy()` trafiłby
+            // w mapę, której jeszcze nie ma, a kontener zostałby oznaczony jako zajęty na zawsze.
+            mountChain.current = mountChain.current.finally(() => map.destroy());
+        };
+        // Silnik i widok startowy czytamy raz — podmiana po starcie nie przeładowuje mapy.
+    }, []);
+    // Bez tego Leaflet zostawia szare pola po każdej zmianie układu strony.
+    useLayoutEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas || typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(() => engineRef.current?.invalidateSize());
+        observer.observe(canvas);
+        return () => observer.disconnect();
+    }, []);
+    // Wypychanie znaczników do silnika — jedyne miejsce, które je rysuje.
+    useEffect(() => {
+        if (ready)
+            engineRef.current?.setMarkers(markers);
+    }, [ready, markers]);
+    // Zmiana źródła kafli w locie — bez przeładowania mapy.
+    useEffect(() => {
+        if (ready) {
+            engineRef.current?.setTileSource(tileUrl ?? KPT_MAP_DEFAULT_TILE_URL, attribution ?? KPT_MAP_DEFAULT_ATTRIBUTION);
+        }
+    }, [ready, tileUrl, attribution]);
+    useEffect(() => {
+        if (ready)
+            engineRef.current?.setMaxBounds(restrictBounds());
+    }, [ready, restrictBounds]);
+    useEffect(() => {
+        if (!ready)
+            return;
+        engineRef.current?.setUserPosition(userPosition, renderUserMarkerHtml({ label: t('map.myLocation'), iconSvgInner: getKptIcon('user') }));
+    }, [ready, userPosition, t]);
+    // Śledzenie pozycji użytkownika. Odmowa zgody wyłącza kontrolkę, ale nie wywraca komponentu.
+    useEffect(() => {
+        if (!showUserLocation || !geolocation) {
+            setUserPosition(null);
+            return;
+        }
+        setLocationBlocked(false);
+        return geolocation.watch((position) => {
+            setUserPosition(position);
+            onUserPositionChange?.(position);
+            if (position && followUser) {
+                const map = engineRef.current;
+                if (map)
+                    map.setView(position.at, Math.max(map.getZoom(), 13));
+            }
+        }, (error) => {
+            setUserPosition(null);
+            setLocationBlocked(true);
+            onUserLocationError?.(error);
+        });
+        // `followUser` czytamy w callbacku, więc nie restartuje nasłuchu.
+    }, [showUserLocation, geolocation]);
+    const popupCategory = popup ? categoryById.get(popup.location.categoryId) : undefined;
+    /**
+     * Odległość otwartego punktu od `distanceFrom` (albo od użytkownika) w metrach. `null`, gdy
+     * nie ma od czego liczyć — treść popupu chowa wtedy wiersz dystansu zamiast pokazywać zero.
+     */
+    const popupDistance = useMemo(() => {
+        if (!popup)
+            return null;
+        const origin = distanceFrom ?? userPosition?.at ?? null;
+        return origin ? haversine(origin, popup.location.at) : null;
+    }, [popup, distanceFrom, userPosition]);
+    /** Pozycje nakładek w pikselach kontenera; zależą od `viewportTick`, czyli od ruchu mapy. */
+    const popupPosition = useMemo(() => {
+        void viewportTick;
+        if (!popup || !engineRef.current || !ready)
+            return null;
+        return engineRef.current.project(popup.location.at);
+    }, [viewportTick, popup, ready]);
+    const contextPosition = useMemo(() => {
+        void viewportTick;
+        if (!contextTarget || !engineRef.current || !ready)
+            return null;
+        return engineRef.current.project(contextTarget.at);
+    }, [viewportTick, contextTarget, ready]);
+    /** Kategorie oferowane w menu „dodaj" — ukryte w legendzie odpadają. */
+    const creatableCategories = useMemo(() => {
+        const hiddenSet = new Set(hidden);
+        return categories.filter((category) => !hiddenSet.has(category.id) && (category.fields?.length || renderCreateForm));
+    }, [categories, hidden, renderCreateForm]);
+    /** Czy jest czym szukać — port bez `search()` nie zasługuje na pole, które nic nie robi. */
+    const searchEnabled = search && !!geocoder?.search;
+    /**
+     * Prostokąt preferowanych wyników: zasięg jawny, a bez niego preset kraju — „Kwiatowa" ma
+     * trafiać w tę pod nosem. To sam bias: adresu z zagranicy dalej da się poszukać.
+     */
+    const searchViewbox = bounds ?? resolveCountryView(country).bounds;
+    /**
+     * Twarde zawężenie do krajów. Jawne `searchOptions.countryCodes` wygrywa; bez niego odcinamy
+     * zagranicę dopiero przy `restrictToCountry` — tam mapa i tak nie pozwoli tam przesunąć widoku.
+     */
+    const searchCountryCodes = searchOptions?.countryCodes ?? (restrictToCountry ? [country] : null);
+    const closeCreate = () => {
+        setCreateOpen(false);
+        setCreateFor(null);
+    };
+    const emitCreate = (value) => {
+        if (!createFor)
+            return;
+        onLocationCreate?.({ at: createFor.at, categoryId: createFor.category.id, value });
+        closeCreate();
+    };
+    const zoomBy = (delta) => {
+        const map = engineRef.current;
+        if (map)
+            map.setView(map.getCenter(), map.getZoom() + delta);
+    };
+    const centreOnUser = () => {
+        const map = engineRef.current;
+        if (!userPosition || !map)
+            return;
+        map.setView(userPosition.at, Math.max(map.getZoom(), 13));
+    };
+    const handleSearchSelect = (result) => {
+        setPopup(null);
+        setContextTarget(null);
+        setSearchPin(result);
+        const map = engineRef.current;
+        // Zasięg (miasto, region) wpasowujemy w kadr, a pojedynczy punkt dostaje `searchZoom`.
+        if (result.bounds)
+            map?.fitBounds(result.bounds, FIT_PADDING);
+        else
+            map?.setView(result.at, searchZoom);
+        onSearchSelect?.(result);
+    };
+    return (_jsxs("div", { className: cn('kpt-map', className), "data-engine": engineKind ?? undefined, style: { ...style, '--kpt-map-height': height }, ...rest, children: [_jsxs("div", { className: "kpt-map__viewport", children: [_jsx("div", { ref: canvasRef, className: "kpt-map__canvas" }), _jsxs("div", { className: "kpt-map__controls", role: "group", "aria-label": t('map.legend'), children: [_jsx("button", { className: "kpt-map__control", type: "button", "aria-label": t('map.zoomIn'), title: t('map.zoomIn'), disabled: !ready, onClick: () => zoomBy(1), children: _jsx("span", { "aria-hidden": "true", children: "+" }) }), _jsx("button", { className: "kpt-map__control", type: "button", "aria-label": t('map.zoomOut'), title: t('map.zoomOut'), disabled: !ready, onClick: () => zoomBy(-1), children: _jsx("span", { "aria-hidden": "true", children: "\u2212" }) }), showUserLocation ? (_jsx("button", { className: "kpt-map__control kpt-map__control--locate", type: "button", "aria-label": locationBlocked ? t('map.locationDenied') : t('map.locateMe'), title: locationBlocked ? t('map.locationDenied') : t('map.locateMe'), disabled: !userPosition, onClick: centreOnUser, children: _jsx("span", { className: "kpt-map__crosshair", "aria-hidden": "true" }) })) : null] }), searchEnabled ? (_jsx("div", { className: "kpt-map__search", children: _jsx(KptMapSearch, { geocoder: geocoder, placeholder: searchPlaceholder, minLength: searchOptions?.minLength ?? 3, debounce: searchOptions?.debounce ?? 300, limit: searchOptions?.limit ?? 5, viewbox: searchViewbox, countryCodes: searchCountryCodes, onSelect: handleSearchSelect, onClear: () => setSearchPin(null) }) })) : null, allowCreate && contextTarget && contextPosition ? (_jsxs("div", { className: "kpt-map__context", role: "menu", "aria-label": t('map.addLocation'), style: { '--_kpt-map-x': `${contextPosition.x}px`, '--_kpt-map-y': `${contextPosition.y}px` }, children: [_jsx("p", { className: "kpt-map__context-title", children: t('map.chooseCategory') }), creatableCategories.length === 0 ? (_jsx("p", { className: "kpt-map__context-empty", children: t('map.empty') })) : (creatableCategories.map((category) => (_jsxs("button", { className: "kpt-map__context-item", type: "button", role: "menuitem", onClick: () => {
+                                    setContextTarget(null);
+                                    setCreateFor({ at: contextTarget.at, category });
+                                    setCreateOpen(true);
+                                }, children: [_jsx("span", { className: "kpt-map__context-dot", "aria-hidden": "true" }), category.label] }, category.id))))] })) : null, popup && popupPosition ? (_jsxs("div", { ref: popupRef, className: "kpt-map__popup", role: "dialog", "data-layout": popupLayout, "aria-label": popup.location.title, style: { '--_kpt-map-x': `${popupPosition.x}px`, '--_kpt-map-y': `${popupPosition.y}px` }, children: [popupLayout === 'plain' ? (_jsx("button", { className: "kpt-map__popup-close", type: "button", "aria-label": t('common.close'), onClick: () => setPopup(null), children: _jsx("span", { "aria-hidden": "true", children: "\u00D7" }) })) : null, popup.group ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "kpt-map__popup-group", children: t('map.clusterItems') }), _jsx("div", { className: "kpt-map__popup-tabs", role: "tablist", children: popup.group.items.map((item) => (_jsx("button", { className: "kpt-map__popup-tab", type: "button", role: "tab", "aria-selected": item.id === popup.location.id, onClick: () => {
+                                                setPopup({ location: item, group: popup.group });
+                                                onLocationClick?.(item);
+                                            }, children: item.title }, item.id))) })] })) : null, _jsx("div", { className: "kpt-map__popup-body", children: renderPopup ? (renderPopup({
+                                    location: popup.location,
+                                    data: popup.location.data,
+                                    category: popupCategory,
+                                    distance: popupDistance,
+                                    close: () => setPopup(null),
+                                })) : (_jsxs(_Fragment, { children: [_jsx("strong", { className: "kpt-map__popup-title", children: popup.location.title }), popupCategory ? _jsx("p", { className: "kpt-map__popup-category", children: popupCategory.label }) : null] })) })] })) : null] }), legend ? (_jsx(KptMapLegend, { className: "kpt-map__legend", categories: categories, hiddenCategories: hidden, onHiddenCategoriesChange: setHidden, counts: counts })) : null, _jsx(KptDialog, { open: createOpen, onOpenChange: (next) => (next ? setCreateOpen(true) : closeCreate()), header: t('map.addLocation'), children: createFor ? (renderCreateForm ? (renderCreateForm({
+                    at: createFor.at,
+                    category: createFor.category,
+                    close: closeCreate,
+                    submit: emitCreate,
+                })) : (_jsx(KptMapCreateDialog, { geocoder: geocoder, category: createFor.category, at: createFor.at, onSave: emitCreate, onCancel: closeCreate }))) : null })] }));
+}

package/dist/map/ports.d.ts

@@ -0,0 +1,76 @@
+import type { KptLatLng, KptMapAddress, KptMapBounds, KptMapGeolocationError, KptMapSearchResult, KptMapSuggestion, KptMapUserPosition } from '@konce-pt/map';
+export interface KptMapSearchOptions {
+    /** Język odpowiedzi. Domyślnie to, co ustawi dostawca. */
+    language?: string;
+    signal?: AbortSignal;
+    /** Ile wyników najwyżej. Domyślnie 5 — to lista podpowiedzi, nie wyszukiwarka pełnotekstowa. */
+    limit?: number;
+    /**
+     * Preferuj wyniki z tego prostokąta. **Nie odcina** reszty świata — adres z zagranicy
+     * dalej da się znaleźć, tylko wypada niżej na liście.
+     */
+    viewbox?: KptMapBounds;
+    /** Twarde zawężenie do krajów (ISO 3166-1 alpha-2). Wyniki spoza nich nie wrócą wcale. */
+    countryCodes?: readonly string[];
+}
+export interface KptMapGeocoderPort {
+    /** `null` = nie udało się ustalić adresu. */
+    reverse(at: KptLatLng, options?: {
+        language?: string;
+        signal?: AbortSignal;
+    }): Promise<KptMapAddress | null>;
+    /**
+     * Geokodowanie wprost: tekst → miejsca. Metoda jest **opcjonalna** — port bez niej po prostu
+     * nie dostaje pola wyszukiwania (komponent go wtedy nie renderuje).
+     */
+    search?(query: string, options?: KptMapSearchOptions): Promise<readonly KptMapSuggestion[]>;
+    /**
+     * Uzupełnia podpowiedź o współrzędne. Wołane **raz, po wybraniu pozycji z listy** — nigdy
+     * w trakcie pisania. Potrzebne tylko dostawcom, których `search()` nie zwraca `at`.
+     */
+    resolve?(suggestion: KptMapSuggestion, options?: {
+        language?: string;
+        signal?: AbortSignal;
+    }): Promise<KptMapSearchResult | null>;
+}
+export interface KptMapGeolocationPort {
+    /**
+     * Śledzi pozycję użytkownika. Zwraca funkcję sprzątającą — tak samo jak efekt Reacta,
+     * więc wpina się bez adaptera.
+     */
+    watch(onPosition: (position: KptMapUserPosition | null) => void, onError: (error: KptMapGeolocationError) => void): () => void;
+}
+/** Geolokalizacja przeglądarki. Brak zgody czy brak API nie wywraca komponentu. */
+export declare function browserGeolocation(options?: PositionOptions): KptMapGeolocationPort;
+/** Stała pozycja — do dem, testów i SSR, gdzie prawdziwej geolokalizacji nie ma. */
+export declare function geolocationStub(at: KptLatLng, accuracy?: number): KptMapGeolocationPort;
+export interface KptNominatimOptions {
+    /** Adres instancji Nominatim. Domyślnie publiczna instancja OSM — patrz ostrzeżenie niżej. */
+    baseUrl?: string;
+    /** Język odpowiedzi (`Accept-Language`). Domyślnie język przeglądarki. */
+    language?: string;
+    /** Szczegółowość: 18 to poziom budynku, 16 ulicy, 10 miasta. Domyślnie 18. */
+    zoom?: number;
+    /**
+     * Najmniejszy odstęp między zapytaniami w milisekundach.
+     *
+     * Sekunda nie jest cechą Nominatima, tylko wymogiem regulaminu **publicznej instancji OSM** —
+     * dlatego domyślna zależy od `baseUrl`: bez niego 1000 ms, z własnym adresem 0.
+     */
+    minIntervalMs?: number;
+}
+/**
+ * Adapter Nominatim (OpenStreetMap): geokodowanie wsteczne i podpowiedzi adresowe.
+ *
+ * Kolejkuje zapytania z odstępem sekundy, bo tego wymaga regulamin publicznej instancji.
+ * Odstęp liczony od zegara, a nie stałym opóźnieniem przed każdym zapytaniem — inaczej
+ * pierwsza podpowiedź po minucie bezczynności też płaciłaby sekundę.
+ *
+ * **Nie rejestruj publicznej instancji w produkcji bez przeczytania jej polityki użycia.**
+ */
+export declare function createNominatimGeocoder(options?: KptNominatimOptions): KptMapGeocoderPort;
+/** Port bez sieci: stała lista podpowiedzi i stały adres. Do dem i testów. */
+export declare function createGeocoderStub(options?: {
+    address?: KptMapAddress | null;
+    suggestions?: readonly KptMapSuggestion[];
+}): KptMapGeocoderPort;