@konce-pt/react 0.11.2 → 0.14.0

package/dist/map/map.js

@@ -1,15 +1,17 @@
+'use client';
 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 { KPT_MAP_DEFAULT_ATTRIBUTION, KPT_MAP_DEFAULT_TILE_URL, clusterLocations, countByCategory, haversine, isCluster, isSplittable, renderClusterHtml, renderMarkerHtml, renderUserMarkerHtml, resolveCountryView, } from '@konce-pt/map';
+import { useCallback, useEffect, useEffectEvent, 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 { KptIcon } from "../icon/icon.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. */
+/** 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 };
@@ -22,15 +24,15 @@ const POPUP_MARGIN = 16;
  * 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` — ' +
+/** 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,
+ * 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`.
  *
@@ -42,22 +44,26 @@ const NO_ENGINE_ERROR = 'KptMap: brak silnika mapy. Podaj fabrykę przez prop `e
  *   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 }) {
+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, searchSpeech = false, searchSpeechLang, searchSpeechColor, geocoder = null, popupLayout = 'plain', distanceFrom = null, height = '480px', tileUrl = null, attribution = null, engine, renderPopup, renderCreateForm, onLocationClick, onClusterClick, onLocationCreate, onSearchSelect, onViewChange, onUserPositionChange, onUserLocationError, onEngineError, 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
+     * 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);
+    /**
+     * Silnik po udanym `init()` - w stanie, nie tylko w refie, bo render czyta z niego pozycje
+     * nakładek (`project`). Ref zostaje dla handlerów zdarzeń, które żyją dłużej niż render.
+     */
+    const [liveEngine, setLiveEngine] = useState(null);
+    const ready = liveEngine !== null;
     /** 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. */
+    /** 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);
@@ -65,7 +71,7 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
     const [createOpen, setCreateOpen] = useState(false);
     const [userPosition, setUserPosition] = useState(null);
     const [locationBlocked, setLocationBlocked] = useState(false);
-    /** Ostatni wybrany wynik wyszukiwania — źródło tymczasowej pinezki. */
+    /** Ostatni wybrany wynik wyszukiwania - źródło tymczasowej pinezki. */
     const [searchPin, setSearchPin] = useState(null);
     const [hidden, setHidden] = useControllableState({
         value: hiddenCategories,
@@ -79,7 +85,7 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
         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. */
+    /** Wynik grupowania dla aktualnego zoomu - grupy i punkty pojedyncze. */
     const entries = useMemo(() => {
         if (!cluster)
             return [...visibleLocations];
@@ -106,7 +112,7 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
                     }),
                     size: CLUSTER_SIZE,
                     anchor: { x: CLUSTER_SIZE.width / 2, y: CLUSTER_SIZE.height / 2 },
-                    // Grupy nad pojedynczymi punktami — licznik ma być czytelny.
+                    // Grupy nad pojedynczymi punktami - licznik ma być czytelny.
                     zIndex: 500,
                 };
             }
@@ -144,7 +150,7 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
                 }),
                 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ć.
+                // Nad grupami (500) - to na nią użytkownik właśnie kazał mapie polecieć.
                 zIndex: 600,
             });
         }
@@ -184,7 +190,11 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
      * 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 };
+    // Odświeżane po zatwierdzeniu renderu, nie w jego trakcie - przerwany render nie zostawi w refie danych,
+    // których nigdy nie było na ekranie.
+    useLayoutEffect(() => {
+        latest.current = { entries, allowCreate, popup, contextTarget, onLocationClick, onClusterClick, onViewChange };
+    });
     const emitViewChange = useCallback(() => {
         const map = engineRef.current;
         if (!map)
@@ -199,7 +209,7 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
             return;
         if (isCluster(entry)) {
             latest.current.onClusterClick?.(entry);
-            // Grupa punktów o tej samej współrzędnej nie da się rozbić zoomem — pokaż listę.
+            // 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;
@@ -215,18 +225,21 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
         latest.current.onLocationClick?.(entry);
     }, [autoPanToPopup]);
     /*
-     * Montaż silnika — raz na życie komponentu.
+     * 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".
+     * "w locie", przed rozwiązaniem obietnicy, zostawiłoby oznaczony kontener i drugi montaż
+     * kończyłby się błędem "Map container is already initialized".
      */
+    const reportEngineError = useEffectEvent((error) => {
+        console.error(error);
+        onEngineError?.(error);
+    });
     useEffect(() => {
         let disposed = false;
         const map = engine();
         engineRef.current = map;
-        setEngineKind(map.kind);
         const preset = resolveCountryView(country);
         const canvas = canvasRef.current;
         if (!canvas)
@@ -265,18 +278,24 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
             });
             map.on('markerclick', (id) => onMarkerClick(id));
             setZoom(map.getZoom());
-            setReady(true);
+            setLiveEngine(map);
             emitViewChange();
+        })
+            // Bez tego odrzucony `init()` to "Uncaught (in promise)" i mapa bez słowa wyjaśnienia.
+            .catch((error) => {
+            if (!disposed)
+                reportEngineError(error);
         });
         return () => {
             disposed = true;
             engineRef.current = null;
-            setReady(false);
+            setLiveEngine(null);
             // 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.
+        // Silnik i widok startowy czytamy raz - podmiana po starcie nie przeładowuje mapy.
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- montaż raz na życie komponentu (patrz wyżej)
     }, []);
     // Bez tego Leaflet zostawia szare pola po każdej zmianie układu strony.
     useLayoutEffect(() => {
@@ -287,12 +306,12 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
         observer.observe(canvas);
         return () => observer.disconnect();
     }, []);
-    // Wypychanie znaczników do silnika — jedyne miejsce, które je rysuje.
+    // 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.
+    // 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);
@@ -307,32 +326,42 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
             return;
         engineRef.current?.setUserPosition(userPosition, renderUserMarkerHtml({ label: t('map.myLocation'), iconSvgInner: getKptIcon('user') }));
     }, [ready, userPosition, t]);
+    /*
+     * Włączenie albo podmiana nasłuchu pozycji zeruje jego stan - liczone w renderze (wzorzec
+     * poprzedniej wartości), a nie w efekcie, który pokazałby jedną klatkę starej pozycji.
+     */
+    const watching = showUserLocation && !!geolocation;
+    const [watchSource, setWatchSource] = useState({ watching, geolocation });
+    if (watchSource.watching !== watching || watchSource.geolocation !== geolocation) {
+        setWatchSource({ watching, geolocation });
+        setUserPosition(null);
+        setLocationBlocked(false);
+    }
+    // Handlery nasłuchu widzą zawsze świeże `followUser` i callbacki, a ich zmiana nie restartuje nasłuchu.
+    const handlePosition = useEffectEvent((position) => {
+        setUserPosition(position);
+        onUserPositionChange?.(position);
+        if (position && followUser) {
+            const map = engineRef.current;
+            if (map)
+                map.setView(position.at, Math.max(map.getZoom(), 13));
+        }
+    });
+    const handleLocationError = useEffectEvent((error) => {
+        setUserPosition(null);
+        setLocationBlocked(true);
+        onUserLocationError?.(error);
+    });
     // Śledzenie pozycji użytkownika. Odmowa zgody wyłącza kontrolkę, ale nie wywraca komponentu.
     useEffect(() => {
-        if (!showUserLocation || !geolocation) {
-            setUserPosition(null);
+        if (!showUserLocation || !geolocation)
             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.
+        return geolocation.watch((position) => handlePosition(position), (error) => handleLocationError(error));
     }, [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.
+     * nie ma od czego liczyć - treść popupu chowa wtedy wiersz dystansu zamiast pokazywać zero.
      */
     const popupDistance = useMemo(() => {
         if (!popup)
@@ -343,31 +372,31 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
     /** Pozycje nakładek w pikselach kontenera; zależą od `viewportTick`, czyli od ruchu mapy. */
     const popupPosition = useMemo(() => {
         void viewportTick;
-        if (!popup || !engineRef.current || !ready)
+        if (!popup || !liveEngine)
             return null;
-        return engineRef.current.project(popup.location.at);
-    }, [viewportTick, popup, ready]);
+        return liveEngine.project(popup.location.at);
+    }, [viewportTick, popup, liveEngine]);
     const contextPosition = useMemo(() => {
         void viewportTick;
-        if (!contextTarget || !engineRef.current || !ready)
+        if (!contextTarget || !liveEngine)
             return null;
-        return engineRef.current.project(contextTarget.at);
-    }, [viewportTick, contextTarget, ready]);
-    /** Kategorie oferowane w menu „dodaj" — ukryte w legendzie odpadają. */
+        return liveEngine.project(contextTarget.at);
+    }, [viewportTick, contextTarget, liveEngine]);
+    /** 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. */
+    /** 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
+     * 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.
+     * zagranicę dopiero przy `restrictToCountry` - tam mapa i tak nie pozwoli tam przesunąć widoku.
      */
     const searchCountryCodes = searchOptions?.countryCodes ?? (restrictToCountry ? [country] : null);
     const closeCreate = () => {
@@ -403,11 +432,11 @@ export function KptMap({ locations, categories, country = 'PL', view = null, bou
             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: () => {
+    return (_jsxs("div", { className: cn('kpt-map', className), "data-engine": liveEngine?.kind, 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(KptIcon, { name: "plus" }) }), _jsx("button", { className: "kpt-map__control", type: "button", "aria-label": t('map.zoomOut'), title: t('map.zoomOut'), disabled: !ready, onClick: () => zoomBy(-1), children: _jsx(KptIcon, { name: "minus" }) }), 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, speech: searchSpeech, speechLang: searchSpeechLang, speechColor: searchSpeechColor, 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: () => {
+                                }, 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: "x" }) })) : 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({

package/dist/map/ports.d.ts

@@ -3,10 +3,10 @@ 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. */
+    /** 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
+     * 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;
@@ -20,12 +20,12 @@ export interface KptMapGeocoderPort {
         signal?: AbortSignal;
     }): Promise<KptMapAddress | null>;
     /**
-     * Geokodowanie wprost: tekst → miejsca. Metoda jest **opcjonalna** — port bez niej po prostu
+     * 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
+     * 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?: {
@@ -35,17 +35,17 @@ export interface KptMapGeocoderPort {
 }
 export interface KptMapGeolocationPort {
     /**
-     * Śledzi pozycję użytkownika. Zwraca funkcję sprzątającą — tak samo jak efekt Reacta,
+     * Ś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. */
+/** 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. */
+    /** 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;
@@ -54,7 +54,7 @@ export interface KptNominatimOptions {
     /**
      * Najmniejszy odstęp między zapytaniami w milisekundach.
      *
-     * Sekunda nie jest cechą Nominatima, tylko wymogiem regulaminu **publicznej instancji OSM** —
+     * 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;
@@ -63,7 +63,7 @@ export interface KptNominatimOptions {
  * 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
+ * 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.**

package/dist/map/ports.js

@@ -26,7 +26,7 @@ function kindOf(error) {
         return 'unavailable';
     return 'timeout';
 }
-/** Stała pozycja — do dem, testów i SSR, gdzie prawdziwej geolokalizacji nie ma. */
+/** Stała pozycja - do dem, testów i SSR, gdzie prawdziwej geolokalizacji nie ma. */
 export function geolocationStub(at, accuracy = 30) {
     return {
         watch(onPosition) {
@@ -42,7 +42,7 @@ const NOMINATIM_MIN_INTERVAL_MS = 1000;
  * 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
+ * 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.**
@@ -50,7 +50,7 @@ const NOMINATIM_MIN_INTERVAL_MS = 1000;
 export function createNominatimGeocoder(options = {}) {
     const baseUrl = options.baseUrl ?? NOMINATIM_URL;
     const minInterval = options.minIntervalMs ?? (options.baseUrl ? 0 : NOMINATIM_MIN_INTERVAL_MS);
-    /** Ogon kolejki — każde kolejne zapytanie czeka na swoją kolej. */
+    /** Ogon kolejki - każde kolejne zapytanie czeka na swoją kolej. */
     let next = Promise.resolve();
     let lastAt = 0;
     const slot = () => {
@@ -89,7 +89,7 @@ export function createNominatimGeocoder(options = {}) {
                 return toAddress((await response.json()));
             }
             catch {
-                // Brak adresu to nie awaria formularza — pole zostaje puste.
+                // Brak adresu to nie awaria formularza - pole zostaje puste.
                 return null;
             }
         },
@@ -147,7 +147,7 @@ function toAddress(place) {
     return {
         street,
         houseNumber,
-        // Jedno pole „Adres" — ulica z numerem, bo tak wypełnia się formularz.
+        // Jedno pole "Adres" - ulica z numerem, bo tak wypełnia się formularz.
         address: [street, houseNumber].filter(Boolean).join(' '),
         city: address.city ?? address.town ?? address.village ?? address.municipality ?? address.hamlet ?? '',
         postcode: address.postcode ?? '',
@@ -167,7 +167,7 @@ function toSuggestion(place) {
         id: String(place.place_id ?? place.display_name ?? at.lat + ':' + at.lng),
         label: place.display_name ?? '',
         at,
-        // Punktowy „prostokąt" pojedynczego budynku nie nadaje się do wpasowania w kadr.
+        // Punktowy "prostokąt" pojedynczego budynku nie nadaje się do wpasowania w kadr.
         bounds: bounds && isFittableBounds(bounds) ? bounds : undefined,
         address: toAddress(place) ?? undefined,
     };

package/dist/map-entry/public-api.js

@@ -1,5 +1,5 @@
 /*
- * @konce-pt/react/map — mapa z konfigurowalnymi znacznikami. Osobny subpath, bo silnik mapowy
+ * @konce-pt/react/map - mapa z konfigurowalnymi znacznikami. Osobny subpath, bo silnik mapowy
  * i style mapy są ciężkie względem rdzenia biblioteki i nie każda aplikacja ich potrzebuje.
  *
  * Silnik Leaflet wymaga zainstalowanej paczki `leaflet` (peer opcjonalny) i arkusza
@@ -14,6 +14,6 @@ export { KptMapHoursField } from "../map/map-hours-field.js";
 export { KptMapImageField } from "../map/map-image-field.js";
 // Porty: geokoder i geolokalizacja. W Reakcie podaje się je propem, nie przez DI.
 export { browserGeolocation, geolocationStub, createNominatimGeocoder, createGeocoderStub } from "../map/ports.js";
-// Silniki i rdzeń (pure TS) — wspólne z portem Angulara.
+// Silniki i rdzeń (pure TS) - wspólne z portem Angulara.
 export { createLeafletEngine, createGoogleEngine, loadGoogleMapsApi } from '@konce-pt/map';
 export { isCluster, clusterLocations, dominantCategory, countByCategory, isSplittable, KPT_CLUSTER_DEFAULTS, KPT_MAP_COUNTRIES, KPT_MAP_DEFAULT_COUNTRY, countryPreset, countryCodes, resolveCountryView, centerOfBounds, project, unproject, boundsOf, boundsCenter, isFittableBounds, KPT_MIN_FIT_SPAN, boundsContain, padBounds, haversine, metersPerPixel, zoomForBounds, clampLat, normalizeLng, worldSize, KPT_TILE_SIZE, KPT_MAX_LATITUDE, KPT_EARTH_RADIUS, renderMarkerHtml, renderClusterHtml, renderUserMarkerHtml, colorVarOf, contrastVarOf, foregroundVarOf, clusterTier, KPT_MAP_DEFAULT_TILE_URL, KPT_MAP_DEFAULT_ATTRIBUTION, parseTime, formatTime, isoWeekday, isOpenAt, isAlwaysOpen, nextChange, weekdayName, groupWeek, emptyWeek, formatDistance, formatLatLng, } from '@konce-pt/map';

package/dist/megamenu/llms.txt

@@ -1,13 +1,13 @@
 # KptMegamenu (@konce-pt/react)
 
-A mega menu — a horizontal bar with a wide, multi-column panel.
+A mega menu - a horizontal bar with a wide, multi-column panel.
 Import: `import { KptMegamenu } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-megamenu-host">
       <div class="kpt-megamenu" role="menubar" aria-orientation="horizontal" aria-label="Main menu">
         <button class="kpt-megamenu__top is-open" role="menuitem" tabindex="0"
-                aria-haspopup="menu" aria-expanded="true" aria-controls="kpt-megamenu-r1">Products …caret…</button>
+                aria-haspopup="menu" aria-expanded="true" aria-controls="kpt-megamenu-r1">Products ...caret...</button>
       </div>
     </div>
     <!-- while open, in a portal: -->
@@ -19,9 +19,9 @@ Import: `import { KptMegamenu } from '@konce-pt/react';`
     </div>
 
 ## Props
-- `items`: `KptMenuItem<T>[]` — three levels: top item → `items` (columns) → column `items` (links)
-- `onSelect(link)` — a picked link from a column, or a top item without columns
-- `ariaLabel`: string — the bar's name for screen readers, e.g. "Main menu"
+- `items`: `KptMenuItem<T>[]` - three levels: top item -> `items` (columns) -> column `items` (links)
+- `onSelect(link)` - a picked link from a column, or a top item without columns
+- `ariaLabel`: string - the bar's name for screen readers, e.g. "Main menu"
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The panel is anchored to the whole bar
@@ -32,7 +32,7 @@ without closing the panel, so browsing across sections costs one click each.
 ## Examples
     <KptMegamenu items={items} onSelect={onSelect} />
 
-    // top → columns → links
+    // top -> columns -> links
     const items: KptMenuItem[] = [{
       label: 'Products',
       items: [
@@ -43,7 +43,7 @@ without closing the panel, so browsing across sections costs one click each.
 
 ## Links (`url`)
 An entry with `url` and no children (and not disabled) renders as a real `<a href>` with the same
-look, so the browser handles navigation — opening in a new tab, the status-bar preview. `onSelect`
+look, so the browser handles navigation - opening in a new tab, the status-bar preview. `onSelect`
 still fires before the browser follows the link.
 
 ## Tokens
@@ -64,3 +64,14 @@ along it, `ArrowDown` (or `Enter`/`Space`) opens the panel on the first link, `A
 In the panel `ArrowDown`/`ArrowUp`/`Home`/`End` walk through all links column by column,
 `ArrowLeft`/`ArrowRight` show the neighbouring item's panel, `Escape` or `Tab` close it and return
 focus to the top item.
+
+## Router
+Links are plain `<a href>`, so without a router a click reloads the page. `onNavigate` fires on a plain
+click (left button, no Ctrl/Cmd/Shift, no `target="_blank"`) with `{ item, url, event }`: call
+`event.preventDefault()` and navigate with your router. Modified clicks stay native (a new tab, a new
+window). The library depends on no router.
+
+    <KptMegamenu items={items} onNavigate={({ event, url }) => { event.preventDefault(); navigate(url); }} />
+
+## When to use it
+The `menubar`/`menu` roles switch a screen reader into application mode: page navigation by headings and links stops, and arrow keys are expected. That fits an application menu (File, Edit, View) or a large product menu. For plain site navigation (a few links in a header) the WAI-ARIA APG recommends the disclosure pattern instead - a `<nav>` with buttons carrying `aria-expanded` and ordinary link lists - which you can build from `kpt-button` and lists. The menu does not render a third level: nested `items` of a submenu item are ignored.

package/dist/megamenu/megamenu.d.ts

@@ -1,15 +1,21 @@
 import { type ComponentPropsWithRef } from 'react';
+import { type KptNavigateEvent } from '../shared/types.ts';
 import type { KptMenuItem } from '../menu/menu-item.ts';
 export interface KptMegamenuProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect'> {
     items?: readonly KptMenuItem<T>[];
     onSelect?: (item: KptMenuItem<T>) => void;
-    /** Nazwa belki dla czytników ekranu, np. „Menu główne”. */
+    /**
+     * Zwykły klik w pozycję z `url`. Aplikacja z routerem woła `event.preventDefault()` i nawiguje
+     * sama - bez tego `<a href>` przeładowuje stronę.
+     */
+    onNavigate?: (event: KptNavigateEvent<KptMenuItem<T>>) => void;
+    /** Nazwa belki dla czytników ekranu, np. "Menu główne". */
     ariaLabel?: string;
 }
 /**
- * Mega-menu — pozioma belka z szerokim, wielokolumnowym panelem.
- * Struktura: pozycja górna → `items` (kolumny) → `items` kolumny (odnośniki).
- * Pozycja górna bez kolumn działa jak akcja — wywołuje `onSelect` zamiast otwierać pusty panel.
+ * Mega-menu - pozioma belka z szerokim, wielokolumnowym panelem.
+ * Struktura: pozycja górna -> `items` (kolumny) -> `items` kolumny (odnośniki).
+ * Pozycja górna bez kolumn działa jak akcja - wywołuje `onSelect` zamiast otwierać pusty panel.
  *
  * Panel kotwiczy się do CAŁEJ belki, nie do pojedynczego przycisku: jest szeroki, więc ma
  * zaczynać się przy krawędzi menu, a nie przy przypadkowej pozycji, w którą kliknięto.
@@ -17,10 +23,10 @@ export interface KptMegamenuProps<T> extends Omit<ComponentPropsWithRef<'div'>,
  * Klawiatura jak w `KptMenubar`: belka to jeden przystanek Tab, strzałki w lewo/prawo
  * i `Home`/`End` chodzą po pozycjach górnych, strzałka w dół (albo `Enter`/spacja) otwiera panel
  * z fokusem na pierwszym odnośniku. W panelu strzałki w górę/dół przechodzą po wszystkich
- * odnośnikach kolumna po kolumnie, w lewo/prawo — do panelu sąsiedniej pozycji, a `Escape`
+ * odnośnikach kolumna po kolumnie, w lewo/prawo - do panelu sąsiedniej pozycji, a `Escape`
  * zamyka panel i oddaje fokus belce.
  *
  * @example
  * <KptMegamenu items={items} onSelect={onSelect} />
  */
-export declare function KptMegamenu<T>({ items, onSelect, ariaLabel, className, ...rest }: Readonly<KptMegamenuProps<T>>): import("react").JSX.Element;
+export declare function KptMegamenu<T>({ items, onSelect, onNavigate, ariaLabel, className, ...rest }: Readonly<KptMegamenuProps<T>>): import("react").JSX.Element;