@konce-pt/angular 0.7.0 → 0.7.5

package/map/src/lib/llms.txt

@@ -0,0 +1,741 @@
+# KptMap (kpt-map)
+
+Mapa z konfigurowalnymi znacznikami: kategorie z kolorem i ikoną, grupowanie z licznikiem,
+popup szczegółów o szablonie zależnym od kategorii, gotowa karta miejsca, legenda, wyszukiwarka
+adresów i dodawanie lokalizacji prawym przyciskiem myszy. Domyślny silnik to Leaflet + OpenStreetMap; API komponentu
+nie zna silnika, więc drugi adapter (Google Maps) podmienia się samym providerem.
+
+Import: `import { KptMap, KptMapPoiCard, KptMapSearch } from '@konce-pt/angular/map';`
+
+## Wymagania (aplikacja)
+
+Poniżej domyślny silnik, Leaflet. Alternatywa — Google Maps — nie wymaga żadnej paczki
+ani arkusza, za to wymaga klucza API i `mapId`; patrz sekcja „Silniki".
+
+1. Zależność **opcjonalna** `leaflet` — biblioteka jej nie instaluje:
+
+       pnpm add leaflet
+
+2. Styl Leafleta — jak `@angular/cdk/overlay-prebuilt.css`, przez `angular.json → styles[]`,
+   NIE jako `import` w `main.ts` (Angular CLI zrobiłby z tego osierocony chunk):
+
+       node_modules/leaflet/dist/leaflet.css
+
+   Vite/webpack: `import 'leaflet/dist/leaflet.css';`
+
+3. Provider silnika w bootstrapie:
+
+       bootstrapApplication(App, { providers: [provideKptLeafletMap()] });
+
+Bez zainstalowanej paczki `leaflet` komponent kompiluje się i importuje bez błędu —
+dopiero próba wyrenderowania mapy kończy się czytelnym komunikatem z instrukcją.
+Leaflet ładujemy dynamicznym `import()`, więc nie obciąża aplikacji, które mapy nie używają.
+
+## Selektor
+
+`kpt-map` — element blokowy. Wysokość ustawia `[height]` (domyślnie `480px`).
+
+## Wejścia
+
+- `locations`: `readonly KptMapLocation<T>[]` — **wymagane**
+- `categories`: `readonly KptMapCategory[]` — **wymagane**
+- `country`: `string` = `'PL'` — preset widoku startowego; nieznany kod cofa się do Polski
+- `view`: `{ center, zoom } | null` — jawny widok; nadpisuje `country`
+- `bounds`: `KptMapBounds | null` — jawny zasięg; nadpisuje `country` i `view`
+- `restrictToCountry`: `boolean` = `false` — blokuje przesuwanie poza zasięg kraju/`bounds`
+- `cluster`: `boolean` = `true`
+- `clusterOptions`: `{ gridSize?, maxZoom?, minPoints? }` — domyślnie `60 / 16 / 2`
+- `clusterColorBy`: `'dominant' | 'none'` = `'none'` — czy grupa bierze kolor najliczniejszej kategorii
+- `legend`: `boolean` = `true` — renderuje `kpt-map-legend` pod mapą
+- `legendCounts`: `boolean` = `true` — liczniki przy pozycjach legendy
+- `showUserLocation`: `boolean` = `false`
+- `followUser`: `boolean` = `false` — centruje mapę przy każdej nowej pozycji
+- `allowCreate`: `boolean` = `false` — menu „Dodaj lokalizację" pod prawym przyciskiem
+- `search`: `boolean` = `false` — wyszukiwarka adresów w rogu mapy; wymaga portu
+  `KPT_MAP_GEOCODER` **z metodą `search()`**, bez niego pole się nie renderuje
+- `searchPlaceholder`: `string` = `''` — pusty oddaje głos słownikowi
+- `searchOptions`: `{ minLength?, debounce?, limit?, countryCodes? }` — domyślnie `3 / 300 / 5`
+- `searchZoom`: `number` = `16` — zoom dla wyniku bez własnego zasięgu
+- `searchMarker`: `boolean` = `true` — tymczasowa pinezka w znalezionym punkcie
+- `geocoder`: `KptMapGeocoderPort | null` = `null` — geokoder **tej** mapy; wygrywa nad
+  `KPT_MAP_GEOCODER` z DI i obsługuje oba kierunki: wyszukiwarkę i podpowiadanie adresu
+  w formularzu dodawania
+- `popupLayout`: `'plain' | 'card'` = `'plain'` — `card` oddaje popup w całości treści:
+  bez paddingu, szerszy (`--kpt-map-popup-width-card`), z przewijaniem po przekroczeniu
+  `--kpt-map-popup-max-height` i bez wbudowanego krzyżyka (daje go karta)
+- `distanceFrom`: `KptLatLng | null` = `null` — punkt odniesienia dystansu podawanego
+  szablonowi popupu; `null` znaczy „pozycja użytkownika z `KPT_MAP_GEOLOCATION`"
+- `height`: `string` = `'480px'`
+- `tileUrl`: `string | null` — domyślnie kafle OSM (patrz „Kafle" niżej); **bez znaczenia dla silnika Google**
+- `attribution`: `string | null` — domyślnie `© OpenStreetMap contributors`; jw.
+- `engine`: `KptMapEngineFactory | null` — silnik tej mapy; wygrywa nad `KPT_MAP_ENGINE` z DI
+  (patrz „Silniki")
+
+## Model / zdarzenia
+
+- `hiddenCategories`: `model<string[]>` — identyfikatory kategorii ukrytych w legendzie
+- `locationClick`: `KptMapLocation<T>`
+- `clusterClick`: `KptMapCluster<T>`
+- `locationCreate`: `{ at, categoryId, value }` — komponent **nie** dopisuje nic do `locations`;
+  źródłem prawdy jest aplikacja
+- `searchSelect`: `KptMapSearchResult` — wybrano podpowiedź; mapa **sama** przeniosła już widok
+- `viewChange`: `{ center, zoom, bounds }` — po zakończeniu ruchu mapy
+- `userPositionChange`: `KptMapUserPosition | null`
+- `userLocationError`: `KptMapGeolocationError`
+
+## KptMapCategory
+
+    { id: 'closure', label: 'Zamknięcie', color: 'danger', icon: 'lock',
+      shape: 'pin', legend: true, fields: [ … ] }
+
+`color` to rola z warstwy semantycznej (`primary | success | warning | danger | info | muted`)
+albo gotowe `var(--kpt-*)`. Literały (`#c00`, `rgb(...)`) są zablokowane na poziomie typu —
+kontrakt repo wymaga tokenów.
+
+Rola daje **trzy** zmienne, zależnie od tego, czym element jest:
+
+| funkcja | do czego | `muted` daje |
+|---|---|---|
+| `colorVarOf()` | tło (pinezka, krążek legendy, grupa) | `--kpt-color-muted` (neutral-100) |
+| `contrastVarOf()` | glif **na** tym tle | `--kpt-color-on-muted` (neutral-800) |
+| `foregroundVarOf()` | glif stojący wprost na powierzchni, bez tła | `--kpt-color-on-surface-muted` |
+
+Pomyłka boli tylko przy `muted`, bo to jedyna rola, której `--kpt-color-*` jest kolorem tła,
+a nie treści — pozostałe są nasycone i czytają się w obu funkcjach. Stąd trzecia funkcja:
+karta miejsca maluje ikonę kategorii wprost na tle karty i `colorVarOf()` dałby jej
+neutral-100 na bieli. `icon` to nazwa z `KptIconRegistry` (pełny Tabler dodaje
+`provideKptTablerIcons()`). `shape`: `pin` (domyślnie, kotwiczy czubkiem), `dot`, `square`.
+
+## KptMapLocation
+
+    { id: 'w1', at: { lat: 51.11, lng: 17.04 }, categoryId: 'opening',
+      title: '2210 · Wrocław', data: { … } }
+
+`title` jest wymagany — trafia do `aria-label` znacznika. `data` jest dowolne i trafia
+do szablonu popupu.
+
+## Szablony
+
+`kptMapPopup` — popup szczegółów, wybierany po kategorii. Szablon bez atrybutu `category`
+jest wariantem zapasowym; bez żadnego szablonu komponent pokazuje tytuł i nazwę kategorii.
+
+    <kpt-map [locations]="locations()" [categories]="categories">
+      <ng-template kptMapPopup category="closure" let-loc let-d="data">
+        <strong>{{ loc.title }}</strong>
+        <p>Zamknięcie · {{ d.status }}</p>
+        <kpt-button size="sm" (click)="openCard(loc)">Otwórz kartę projektu</kpt-button>
+      </ng-template>
+      <ng-template kptMapPopup let-loc><strong>{{ loc.title }}</strong></ng-template>
+    </kpt-map>
+
+Kontekst: `$implicit` = lokalizacja, `data` = `location.data` (typ `T | undefined`, bo `data`
+jest opcjonalne), `category`, `distance`, `close()`.
+
+`distance` to odległość punktu w **metrach** od `[distanceFrom]`, a bez niego od pozycji
+użytkownika. `null`, gdy nie ma punktu odniesienia — geolokalizacja wyłączona albo odmówiona.
+Formatuje się ją `formatDistance(metry, locale)` z rdzenia; `kpt-map-poi-card` robi to sam.
+
+Typ `data` domyślnie jest luźny — Angular nie przenosi generyka z `kpt-map` na dyrektywę osadzoną
+w jego treści. Kto chce wnioskowania, wiąże `[kptMapPopupTypeFor]` z tą samą tablicą, którą karmi
+mapę (input istnieje wyłącznie po to, w runtime nieużywany):
+
+    <ng-template kptMapPopup [kptMapPopupTypeFor]="locations()" category="opening" let-d="data">
+      <p>{{ d?.address }}</p>
+    </ng-template>
+
+Popup otwarty przy krawędzi kontenera przesuwa mapę tak, żeby się zmieścił (auto-pan mierzy go
+po pierwszym renderze — przed nim nie znamy jego wymiarów).
+
+`kptMapCreateForm` — własny formularz dodawania. Jego obecność wyłącza formularz
+budowany ze schemy kategorii.
+
+    <ng-template kptMapCreateForm let-api>
+      <!-- api: { at, category, close(), submit(value) } -->
+    </ng-template>
+
+## KptMapPoiCard (kpt-map-poi-card)
+
+Gotowa karta miejsca do popupu: dystans, zdjęcie 16:9, przycisk główny + udostępnij + ulubione,
+wiersz kategorii, rozwijane godziny otwarcia ze statusem otwarte/zamknięte oraz wiersze
+kontaktowe (telefon, www, e-mail, współrzędne) z akcjami i kopiowaniem do schowka.
+
+    <kpt-map [locations]="places()" [categories]="categories" popupLayout="card">
+      <ng-template kptMapPopup [kptMapPopupTypeFor]="places()"
+                   let-loc let-d="data" let-category="category"
+                   let-distance="distance" let-close="close">
+        <kpt-map-poi-card
+          [poi]="poiOf(loc, d)"
+          [distance]="distance"
+          [category]="category ?? null"
+          primaryLabel="Wyznacz trasę"
+          (primaryAction)="planRoute($event)"
+          (closed)="close()"
+        />
+      </ng-template>
+    </kpt-map>
+
+Wejścia:
+
+- `poi`: `KptMapPoi` — **wymagane**
+- `distance`: `number | null` = `null` — metry; `null` chowa wiersz dystansu
+- `category`: `KptMapCategory | null` = `null` — ikona, kolor i etykieta wiersza kategorii
+- `primaryLabel`: `string` = `''` — pusta chowa przycisk główny
+- `showShare`, `showFavourite`, `closable`: `boolean` = `true`
+- `favourite`: `model<boolean>` = `false`
+- `hoursExpanded`: `model<boolean>` = `false`
+
+Wyjścia: `primaryAction: KptMapPoi`, `closed: void`, `shared: KptMapPoi`.
+
+`KptMapPoi` jest **osobne od modelu domenowego** — mapowanie `location.data → KptMapPoi` robi
+aplikacja. Biblioteka nie zgaduje, które pole jest telefonem:
+
+    { title, address?, photo?, photoAlt?, hours?, phone?, email?, website?, at?,
+      facts?: [{ icon?, label, value }] }
+
+`photo` przyjmuje adres albo `data:` — karta nie rozróżnia. Bez niego rysuje zastępnik z ikoną,
+zamiast zwijać kadr do zera. `facts` to dowolne wiersze „ikona · etykieta · wartość" pod kontaktami.
+
+Zachowania warte zapamiętania:
+
+- **Zdjęcie** jest w kadrze 16:9 z `object-fit: cover` na zwykłym `<img>`, nie na `kpt-image` —
+  tamten jest `inline-block` z `height: auto` i kadru nie utrzyma.
+- **Godziny** to natywny disclosure (`aria-expanded` + `aria-controls`), nie `kpt-accordion`:
+  `KptAccordionPanel.title` przyjmuje sam string, a nagłówek musi zmieścić ikonę, status
+  w kolorze i chevron. Status liczy `isOpenAt()`; dni sklejają się przez `groupWeek()`.
+- **Akcje wierszy** są zawsze w DOM. Ukrywa je wyłącznie `@media (hover: hover) and
+  (pointer: fine)`, a `:hover`/`:focus-within` je odsłania — na dotyku i z klawiatury
+  są dostępne bez sztuczek.
+- **Kopiowanie** idzie przez `navigator.clipboard`; bez tego API przycisk się nie renderuje.
+  Po sukcesie ikona zmienia się na `check`, a komunikat leci do `aria-live`.
+- **Udostępnianie** woła `navigator.share()`, a bez niego kopiuje adres. Anulowanie arkusza
+  przez użytkownika nie jest błędem i nie emituje `shared`.
+- **Tytuł to `<p role="heading" aria-level="3">`, nie `<h3>`.** Style komponentów siedzą
+  w `@layer kpt.components`, a CSS aplikacji spoza warstw wygrywa z nimi zawsze — zwykły
+  `<h3>` łapałby każdą regułę `h3 { … }` z układu strony (w playgroundzie robiła z tytułu
+  miejsca 13-pikselowy uppercase). Dla czytnika ekranu to dalej nagłówek poziomu 3.
+- Karta nie ustawia własnego `role` na hoście — popup `kpt-map` jest już `role="dialog"`.
+
+Anatomia i przewijanie:
+
+    kpt-map-poi-card
+      .kpt-map-poi__head      tytuł + krzyżyk        — nieruchome
+      .kpt-map-poi__meta      dystans + adres        — nieruchome
+      .kpt-map-poi__scroll    zdjęcie, akcje, kategoria, godziny, kontakty, aria-live
+
+Nagłówek stoi, przewija się wyłącznie `__scroll`. Dystans i adres należą do bloku
+nagłówkowego, bo są częścią tożsamości miejsca — żeby przewijały się razem z treścią,
+wystarczy przenieść `__meta` do `__scroll`.
+
+Warunkiem jest to, że `popupLayout="card"` **oddaje przewijanie karcie**: `.kpt-map__popup-body`
+dostaje wtedy `display: flex` i `overflow: hidden`, a karta pełną wysokość popupu. Dopóki
+przewija kontener nadrzędny, nagłówka nie da się przypiąć bez `sticky` i ujemnych marginesów.
+Sam popup nie dostaje `overflow: hidden` — strzałka `::after` wisi na `top: 100%` i zostałaby
+ucięta. Karta poza popupem (stories, dowolny wrapper bez limitu wysokości) nie przewija się
+wcale: `__scroll` ma `flex: 0 1 auto` i bez sufitu wysokości po prostu rośnie.
+
+## Dodawanie lokalizacji
+
+Prawy klik → menu z kategoriami → `kpt-dialog` z formularzem. Domyślnie formularz powstaje
+z `category.fields` na Signal Forms. Typy pól i kontrolki:
+
+| `type` | kontrolka | uwagi |
+|---|---|---|
+| `text` | `kpt-input` | |
+| `textarea` | `kpt-textarea` | |
+| `number` | `kpt-input-number` | `min`/`max` ze schemy idą przez walidatory, nie przez `[min]` |
+| `date` | `kpt-datepicker` | `min`/`max` jako daty ISO |
+| `select` / `multiselect` | `kpt-select` (`multiple`) | wymaga `options` |
+| `checkbox` | `kpt-checkbox` | `placeholder` służy za etykietę przy polu |
+| `tel` | `kpt-input type="tel"` | bez walidacji formatu — numery bywają dziwne |
+| `email` | `kpt-input type="email"` | walidator `email()` |
+| `url` | `kpt-input type="url"` | wzorzec `https?://…` |
+| `image` | `kpt-map-image-field` | wybór pliku **albo** wklejony adres; wartość to `string` |
+| `hours` | `kpt-map-hours-field` | wartość to `KptMapOpeningHours` |
+
+Współrzędne z kliknięcia są pokazane, ale nieedytowalne.
+
+`image` czyta plik `FileReader.readAsDataURL()` i **nigdzie go nie wysyła** — biblioteka nie ma
+wiedzy o storage'u aplikacji. Limit 2 MB jest realny, nie ozdobny: data URL puchnie o ~⅓,
+a cała wartość leci w `locationCreate`. Wpisanie adresu czyści wybrany plik i odwrotnie.
+
+`hours` daje siedem wierszy od poniedziałku (nazwy dni z `Intl`, nie ze słownika), po dwa
+przedziały na dobę, znacznik „zamknięte" i skrót „tak samo przez cały tydzień" kopiujący
+poniedziałek na resztę. Dzień nieoznaczony jako zamknięty musi mieć obie godziny — inaczej
+formularz jest `invalid`.
+
+Godzinę wybiera się na `kpt-datepicker selectionMode="time"` (tarcza zegara, `minuteStep=5`),
+nie na natywnym `<input type="time">` — ten renderuje własny, systemowy dropdown, którego
+nie da się ostylować i który wygląda obco pośród kontrolek biblioteki. Wartość jest ta sama:
+`HH:mm` albo pusty string.
+
+**Ograniczenie:** przy dynamicznej schemie model to `Record<string, unknown>`, więc pola
+nie są typowane statycznie. Kto potrzebuje typów — podaje własny `kptMapCreateForm`.
+
+Bramka „nie strasz czerwienią świeżego formularza" siedzi w prezentacji (`touched() &&
+invalid()`), a nie w walidatorze — zgodnie z kontraktem Signal Forms w tym repo.
+
+## Podpowiadanie adresu (geokodowanie wsteczne)
+
+Pola formularza „dodaj lokalizację" mogą wypełnić się adresem klikniętego punktu. Dwa warunki:
+pole ma `autofill` wskazujące część adresu, a mapa ma port — z DI (`KPT_MAP_GEOCODER`)
+albo z wejścia `[geocoder]`, które wygrywa.
+
+    { key: 'city',    type: 'text', label: 'Miasto', autofill: 'city' },
+    { key: 'address', type: 'text', label: 'Adres',  autofill: 'address' },
+
+Części adresu (`KptMapAddressPart`): `street`, `houseNumber`, `address` (ulica z numerem),
+`city`, `postcode`, `state`, `county`, `country`, `countryCode`, `label` (pełny adres jednym
+ciągiem). Działa tylko dla pól `text` i `textarea` — data ani liczba nie przyjmą fragmentu adresu.
+
+**Podpowiedź nigdy nie nadpisuje tego, co użytkownik wpisał** — wypełniane są wyłącznie pola
+puste w chwili odpowiedzi. Brak portu albo nieudane zapytanie nie blokuje formularza: pola
+zostają puste, a pod współrzędnymi pojawia się notka.
+
+Gotowy adapter (opt-in, NIE jest rejestrowany domyślnie):
+
+    providers: [provideKptLeafletMap(), provideKptNominatimGeocoder({ language: 'pl' })]
+
+**Polityka Nominatim.** Publiczna instancja `nominatim.openstreetmap.org` dopuszcza maksymalnie
+jedno zapytanie na sekundę, wymaga rozpoznawalnego `Referer`/`User-Agent` i zabrania masowego
+odpytywania; ruch może zostać zablokowany bez uprzedzenia, w szczególności komercyjny. Adapter
+sam kolejkuje zapytania z odstępem sekundy i przerywa je przy zamknięciu okna, ale do produkcji
+podstaw własną instancję (`baseUrl`) albo komercyjnego dostawcę przez własny `KPT_MAP_GEOCODER`:
+
+    export interface KptMapGeocoderPort {
+      reverse(at: KptLatLng, options?): Observable<KptMapAddress | null>;
+      search?(query: string, options?): Observable<readonly KptMapSuggestion[]>;
+      resolve?(suggestion: KptMapSuggestion, options?): Observable<KptMapSearchResult | null>;
+    }
+
+Tylko `reverse()` jest obowiązkowe. Bez `search()` mapa nie pokazuje wyszukiwarki;
+`resolve()` opisano niżej, przy podpowiedziach bez współrzędnych.
+
+**Odstęp między zapytaniami (`minIntervalMs`).** Sekunda nie jest cechą Nominatima, tylko
+wymogiem regulaminu **publicznej instancji OSM** — dlatego domyślna zależy od `baseUrl`:
+
+    provideKptNominatimGeocoder()                                  // 1000 ms
+    provideKptNominatimGeocoder({ baseUrl: 'https://geo.local' })  // 0 ms
+    provideKptNominatimGeocoder({ baseUrl: '…', minIntervalMs: 200 })
+
+Na własnym serwerze nie ma czego respektować, a przy podpowiadaniu w trakcie pisania sekundowa
+zwłoka jest różnicą między „działa" a „zacina się". `0` zdejmuje też kolejkowanie — zapytania
+lecą równolegle. Podstawiając **cudzą, współdzieloną** instancję ustaw wartość jawnie.
+
+Testy i Storybook: `provideKptMapGeocoderStub({ city: 'Warszawa', address: 'Marszałkowska 100' })`.
+
+## Wyszukiwarka adresów (geokodowanie wprost)
+
+`[search]` pokazuje w prawym górnym rogu mapy pole z podpowiedziami. Wpisanie frazy odpytuje
+port geokodera — **ten sam**, co podpowiadanie adresu w formularzu dodawania, tylko
+w drugą stronę; z DI (`KPT_MAP_GEOCODER`) albo z wejścia `[geocoder]`, które wygrywa.
+Metoda `search()` jest w porcie **opcjonalna**: porty napisane przed jej powstaniem dalej
+się kompilują, a mapa bez niej po prostu nie renderuje pola.
+
+    <kpt-map [locations]="places()" [categories]="categories" search
+             (searchSelect)="onFound($event)" />
+
+    // main.ts — bez tego pola nie będzie
+    providers: [provideKptLeafletMap(), provideKptNominatimGeocoder({ language: 'pl' })]
+
+Dwa typy, celowo rozdzielone:
+
+    KptMapSuggestion   = { id, label, at?, bounds?, address? }   // pozycja na liście
+    KptMapSearchResult = KptMapSuggestion & { at: KptLatLng }    // to, co wychodzi ze zdarzenia
+
+`address` to ten sam `KptMapAddress`, co przy geokodowaniu wstecznym — nie ma drugiego modelu adresu.
+
+### Podpowiedzi bez współrzędnych (`resolve()`)
+
+Większość geokoderów pytanych wprost (Nominatim, Photon, Google Geocoding API) podaje `lat`/`lng`
+od razu na liście. **Google Places Autocomplete tego nie robi**: zwraca `placeId` i tekst,
+a współrzędne dociąga się osobnym Place Details. To nie jest dziwactwo jednego dostawcy — na tym
+stoi jego rozliczanie sesyjne, w którym cały ciąg podpowiedzi plus finalne Place Details liczy się
+jako jedno zdarzenie.
+
+Dlatego `search()` zwraca `KptMapSuggestion` (z `at` **opcjonalnym**), a port może dopisać:
+
+    resolve?(suggestion: KptMapSuggestion, options?: { language?, signal? })
+      : Observable<KptMapSearchResult | null>;
+
+Reguła jest jednozdaniowa: **jeśli Twój `search()` nie zwraca `at`, musisz zaimplementować
+`resolve()`.** Kto zwraca współrzędne od razu, tej metody nie potrzebuje — pole nawet jej nie zawoła.
+
+Obsługa siedzi w `kpt-map-search`, nie w `kpt-map`, więc gwarancja obowiązuje tak samo przy polu
+postawionym samodzielnie:
+
+- podpowiedź z `at` → `selected` leci **natychmiast**, bez dodatkowego zapytania;
+- podpowiedź bez `at` → `resolve()` raz, **po wybraniu pozycji**, nigdy w trakcie pisania;
+  panel zostaje otwarty z notą „Szukam…", a `aria-busy` na polu niesie to czytnikowi;
+- `null` albo błąd → etykieta zostaje w polu, lista wraca (można wybrać inną pozycję),
+  a `aria-live` mówi „brak pasujących miejsc";
+- kolejny wybór i wyczyszczenie pola przerywają zapytanie w locie.
+
+**`selected` i `searchSelect` zawsze niosą współrzędne.** Aplikacja nigdy nie sprawdza, czy `at` jest.
+
+Gdy port **nie ma** `resolve()`, podpowiedzi bez `at` w ogóle nie trafiają na listę: pozycja,
+której kliknięcie nie miałoby dokąd polecieć, jest gorsza niż jej brak.
+
+Atrapa umie udawać takiego dostawcę — bez tego ścieżki nie da się pokazać bez klucza API:
+
+    provideKptMapGeocoderStub(address, results, { deferCoordinates: true })
+
+**Po wyborze podpowiedzi mapa przenosi widok sama.** Wynik z `bounds` (miasto, region,
+województwo) dostaje `fitBounds`, a wynik bez nich — `setView` na `[searchZoom]`. Zdarzenie
+`searchSelect` leci już po ruchu i służy aplikacji do jej własnych rzeczy (przestawienie
+`[distanceFrom]`, zapytanie o punkty w okolicy), nie do nawigacji.
+
+Adapter Nominatim **celowo odrzuca zbyt ciasny prostokąt** i zwraca wtedy sam punkt.
+Pojedynczy adres ma tam bounding box rzędu 0,0001°, więc `fitBounds` skakałby na nim do
+górnego limitu zoomu i każdy adres lądowałby w innym przybliżeniu, zależnym od tego, jak
+dostawca obrysował budynek — z progiem adresy trafiają w powtarzalne `[searchZoom]`,
+a miasta dalej wchodzą w kadr w całości.
+
+Regułę trzyma `isFittableBounds(bounds, minSpan?)` z rdzenia (`KPT_MIN_FIT_SPAN` = 0,001°,
+czyli ~100 m) — jest w publicznym API, ma testy i obowiązuje każdy adapter, nie tylko Nominatim.
+Próg wystarczy przekroczyć w **jednej** osi: długa, wąska ulica ma jeden wymiar mikroskopijny
+i dalej zasługuje na `fitBounds`.
+
+**Zawężanie geograficzne.** Zapytanie dostaje `viewbox` z `[bounds]`, a bez nich z presetu
+`[country]` — to sam bias, przestawia kolejność wyników i niczego nie odcina. Twarde
+`countrycodes` dokłada się dopiero przy `restrictToCountry` (mapa i tak nie pozwoli
+przesunąć widoku poza kraj, więc adres z zagranicy byłby nie do pokazania) albo jawnie
+przez `searchOptions.countryCodes`.
+
+**Tymczasowa pinezka** (`[searchMarker]`, domyślnie włączona) idzie tą samą drogą co reszta
+znaczników — przez `engine.setMarkers()` — więc przesuwa się z mapą klatka po klatce.
+Nie należy do `entries()`, więc kliknięcie w nią nic nie otwiera. Znika po wyczyszczeniu
+pola krzyżykiem i po kliknięciu w mapę.
+
+Polityka Nominatim jest tu **ostrzejsza niż przy `reverse()`**, bo podpowiadanie w trakcie
+pisania z natury generuje serie zapytań. Adapter broni się dwoma mechanizmami: pole czeka
+`debounce` (300 ms) od ostatniego znaku i nie pyta poniżej `minLength` (3 znaki), a sam
+adapter trzyma **jedną wspólną kolejkę z `reverse()`** — jedno zapytanie na sekundę na całego
+klienta, nie na metodę. Zapytanie porzucone (kolejny znak, zamknięcie pola) jest przerywane
+`AbortController`-em. Do produkcji i tak podstaw własną instancję albo dostawcę komercyjnego.
+
+Kolejka liczy odstęp **od zegara**, a nie stałym opóźnieniem przed każdym zapytaniem: pierwsze
+po chwili bezczynności leci od razu, a kolejne czeka tylko tyle, ile brakuje do sekundy.
+Górna granica jednego zapytania na sekundę zostaje nienaruszona, ale pierwsza podpowiedź
+nie kosztuje już sekundy w plecy.
+
+### KptMapSearch (kpt-map-search)
+
+Samo pole jest osobnym komponentem — jak legenda, żeby dało się je postawić poza mapą
+(pasek narzędzi aplikacji, panel boczny):
+
+    <kpt-map-search [viewbox]="bounds" (selected)="goTo($event)" (cleared)="clearPin()" />
+
+Wejścia: `placeholder`, `minLength` (3), `debounce` (300), `limit` (5), `countryCodes`,
+`viewbox`, `disabled`, `geocoder` (port tego pola; wygrywa nad DI — taką drogą podaje go
+`kpt-map`). Wyjścia: `selected: KptMapSearchResult`, `cleared: void`.
+Bez portu z `search()` pole renderuje się **wyłączone**, zamiast udawać, że coś znajdzie.
+
+**Dlaczego nie `kpt-autocomplete`** — pytanie wraca, więc na piśmie: tamten filtruje opcje
+po stronie klienta (`includes(q)`), więc wynik geokodera tolerancyjny na literówki albo inaczej
+brzmiący wypadałby z listy; jego wartością jest sam `string`, więc nie ma czym przewieźć
+współrzędnych; i stoi na CDK Overlay, co dołożyłoby `@angular/cdk/overlay-prebuilt.css`
+do wymagań mapy, której poza tym nie potrzebuje. Panel podpowiedzi jest więc rysowany wprost
+w warstwie Angulara nad mapą, tak samo jak popup i menu prawego przycisku.
+
+Debounce stoi na `setTimeout` w efekcie z `onCleanup`, a nie na operatorach rxjs: porty tego
+pakietu używają wyłącznie `Observable`/`of`, a rxjs nie jest zadeklarowany jako
+`peerDependency` biblioteki (wchodzi tranzytywnie przez `@angular/core`).
+
+Wpisany tekst i fraza do odpytania to **dwa osobne sygnały**. Wybór podpowiedzi wpisuje jej
+etykietę do pola, ale nie rusza frazy — inaczej wybór natychmiast odpalałby kolejne zapytanie
+o coś, co właśnie znaleźliśmy.
+
+## Legenda
+
+`kpt-map-legend` — osobny komponent, żeby dało się go umieścić poza mapą. Pozycje są
+przyciskami z `aria-pressed`; kliknięcie chowa kategorię (znika też z grup, liczniki maleją).
+
+    <kpt-map [legend]="false" [(hiddenCategories)]="hidden" … />
+    <kpt-map-legend [categories]="categories" [(hidden)]="hidden" orientation="vertical" />
+
+Wejścia: `categories` (wymagane), `hidden` (model), `counts`, `orientation`, `interactive`.
+
+## Geolokalizacja
+
+`[showUserLocation]` włącza znacznik własnego położenia (ikona `user`) z kręgiem dokładności
+i kontrolkę „wyśrodkuj na mnie". Pozycja idzie przez port DI:
+
+    KPT_MAP_GEOLOCATION → KptBrowserGeolocation (domyślnie)
+    provideKptMapGeolocationStub({ lat: 52.23, lng: 21.01 })   // Storybook, testy
+
+Geolocation API działa **wyłącznie w bezpiecznym kontekście** (HTTPS albo `localhost`).
+Na `http://` z adresem IP przeglądarka odmówi — to nie jest błąd komponentu. Odmowa zgody
+wyłącza kontrolkę i emituje `userLocationError`; komponent nie pokazuje własnego alertu,
+decyzję o komunikacie zostawia aplikacji. Na SSR port zwraca `null`.
+
+## Silniki
+
+Silnik dostarcza fabryka pod tokenem `KPT_MAP_ENGINE`, a komponent rozmawia z nią przez
+interfejs `KptMapEngine` (zero typów Leafleta w sygnaturach). Podział renderowania:
+
+- kafle, panning, zoom, **znaczniki i grupy** → silnik (`L.divIcon` z HTML-em z rdzenia),
+- **popup, kontrolki, menu, legenda, dialog** → warstwa Angulara nad kontenerem mapy.
+
+Znaczniki idą przez silnik, bo muszą przesuwać się z mapą klatka po klatce (Leaflet robi to
+jednym `transform` na panie). Popup jest jeden na raz, więc przeliczanie jego pozycji
+z `engine.project()` przy każdym ruchu jest tanie — a daje pełnego Angulara w treści
+i jedną implementację dla obu silników.
+
+### Dwa silniki
+
+    provideKptLeafletMap()                              // domyślny, bez klucza i konta
+    provideKptGoogleMap({ apiKey, mapId })              // Google Maps JavaScript API
+
+Leaflet wymaga paczki `leaflet` (opcjonalnej) i `leaflet/dist/leaflet.css`. Google nie wymaga
+**żadnej paczki npm** — API dogrywa się skryptem przy pierwszej mapie — ale wymaga klucza,
+konta rozliczeniowego z kartą i `mapId` z konsoli (*Map management → Create Map ID*).
+Bez `mapId` nie działa `AdvancedMarkerElement`, czyli nie będzie znaczników.
+
+|                        | `leaflet`                     | `google`                                  |
+| ---------------------- | ----------------------------- | ----------------------------------------- |
+| `[tileUrl]`/`[attribution]` | działa, wymiana w locie  | **ignorowane** — kafle daje Google         |
+| atrybucja              | kontrolka Leafleta (ODbL)     | logo i linki ToS wbudowane, **nie zasłaniać** |
+| klucz / konto          | niepotrzebne                  | klucz API + billing z kartą                |
+| koszt                  | kafle OSM (bez SLA)           | SKU Dynamic Maps: 10 tys. wczytań/mies. za darmo |
+| geokoder Google        | **niedozwolony**              | dozwolony                                  |
+| zoom                   | całkowity, max 19             | ułamkowy przy gestach, ponad 21            |
+
+**Ostatni wiersz jest powodem, dla którego ten silnik istnieje.** Google Maps Platform Service
+Specific Terms §6.2 (Geocoding API) i §14.2 (Places API) zabraniają używać ich wyników
+„in conjunction with a non-Google map". Adapter Google pod `KPT_MAP_GEOCODER` jest więc zgodny
+z umową **wyłącznie** przy silniku `google` — z domyślnym Leafletem nie. Sama biblioteka
+takiego adaptera nie dostarcza; to decyzja i kod aplikacji.
+
+Dlatego geokoder jest per mapa, a nie per aplikacja: wejście `[geocoder]` (niżej) pozwala
+postawić obok siebie mapę Leafleta z geokoderem OSM i mapę Google z geokoderem Google.
+Globalny provider nie umiałby tego rozstrzygnąć — musiałby złamać regułę po jednej
+ze stron.
+
+### `[engine]` — dwie mapy, dwa silniki, jedna strona
+
+Wejście przyjmuje fabrykę i wygrywa nad `KPT_MAP_ENGINE` z DI. Bez niego nic się nie zmienia.
+
+    readonly google: KptMapEngineFactory = () => createGoogleEngine({ apiKey, mapId });
+
+    <kpt-map [engine]="google" [locations]="places()" [categories]="cats" />
+
+Czytane raz, przy inicjalizacji — podmiana po starcie nie przeładowuje mapy. Brak silnika
+w obu źródłach daje czytelny błąd z instrukcją, a nie `NullInjectorError`.
+
+### `[geocoder]` — port idzie za silnikiem
+
+Symetryczne do `[engine]` i z tego samego powodu: geokoder Google wolno pokazać tylko
+z mapą Google, a to jest własność **mapy**, nie aplikacji. Wejście wygrywa nad
+`KPT_MAP_GEOCODER` z DI i trafia zarówno do wyszukiwarki, jak i do formularza dodawania.
+
+    <kpt-map [engine]="leaflet" search … />                        <!-- port z DI (np. Nominatim) -->
+    <kpt-map [engine]="google" [geocoder]="googleGeocoder" search … />
+
+W odróżnieniu od `[engine]` czytane jest **reaktywnie**: podmiana portu zeruje listę
+podpowiedzi i od następnej frazy pyta nowego dostawcę. `null` w obu źródłach znaczy tyle,
+co dziś brak portu: pole wyszukiwarki się nie renderuje, a formularz nie podpowiada adresu.
+
+To samo wejście ma `kpt-map-search` i `kpt-map-create-dialog`, gdy stoją poza mapą.
+
+**Pisząc adapter Google, idź przez SDK, nie przez REST.** Web service
+`maps.googleapis.com/maps/api/geocode/json` odrzuca klucze ograniczone po domenie:
+
+    { "status": "REQUEST_DENIED",
+      "error_message": "API keys with referer restrictions cannot be used with this API." }
+
+a to jedyna restrykcja, jaka ma sens dla klucza leżącego jawnie w bundlu przeglądarki. CORS na
+tym endpoincie działa, więc nie ma nawet błędu sieci — przychodzi `200` z `REQUEST_DENIED`
+w treści, łatwe do przeoczenia. `google.maps.Geocoder` z załadowanego SDK autoryzuje się tak samo jak sama
+mapa, więc działa z tym samym kluczem — to ten sam SKU, tylko inna droga. Dostęp do API
+daje wyeksportowany loader (ten sam, którego używa silnik):
+
+    const maps = await loadGoogleMapsApi({ apiKey, language: 'pl' });
+    const { Geocoder } = await maps.importLibrary('geocoding');
+    const { results } = await new Geocoder().geocode({ address: 'Marszałkowska 100, Warszawa' });
+
+Uwaga na kształt odpowiedzi: SDK oddaje `location` i `viewport` jako obiekty z metodami
+(`lat()`, `getNorthEast()`), a nie jako pola jak REST. Zapytania SDK **nie da się przerwać**,
+więc `signal` z opcji portu zostaje bez pokrycia — odsubskrybowanie tylko przestaje słuchać.
+Przykład adaptera od początku do końca: `apps/playground/src/pg-map.google-geocoder.ts`.
+
+Silnik trafia na host jako `[data-engine]` (`leaflet` | `google`) — po tym atrybucie stylują
+się nieliczne różnice, np. krąg dokładności (w Leaflecie kółko SVG, w Google element z tłem,
+bo `google.maps.Circle` przyjmuje kolory w opcjach, a tu obowiązują tokeny).
+
+Adapter Google liczy `project()`/`unproject()` **rdzeniem** (`core/geo.ts`), a nie
+`map.getProjection()`: ten bywa `null` do pierwszego `idle` i tak czy owak wymaga przeliczenia
+na piksele kontenera. Dzięki temu popup ląduje piksel w piksel tam samo co przy Leaflecie,
+zgadza się z grupowaniem i radzi sobie z zoomem ułamkowym.
+
+## Rdzeń (pure TS)
+
+`@konce-pt/angular/map` eksportuje rdzeń obliczeń — bez Angulara i bez silnika, przenośny
+do portu React: `clusterLocations`, `dominantCategory`, `countByCategory`, `isSplittable`,
+`project`/`unproject`/`boundsOf`/`haversine`/`metersPerPixel`/`zoomForBounds`/`isFittableBounds`,
+`KPT_MAP_COUNTRIES`/`countryPreset`/`resolveCountryView`,
+`renderMarkerHtml`/`renderClusterHtml`/`colorVarOf`/`contrastVarOf`/`foregroundVarOf`,
+`formatDistance`/`formatLatLng` oraz godziny otwarcia: `parseTime`, `formatTime`, `isoWeekday`,
+`isOpenAt`, `isAlwaysOpen`, `nextChange`, `weekdayName`, `groupWeek`, `emptyWeek`.
+
+Model godzin: `KptMapOpeningHours` = tablica `{ day: 1–7 (ISO), closed?, ranges: [{ from, to }] }`
+w `HH:MM` czasu lokalnego miejsca. `to` mniejsze albo równe `from` znaczy „przez północ";
+`24:00` to prawidłowy koniec doby i przez północ **nie** przechodzi. Brakujący dzień = zamknięte.
+`isOpenAt()` sprawdza dwa dni — bieżący i poprzedni — bo przedział `22:00–01:00` obejmuje
+wczesne godziny dnia następnego. `groupWeek()` skleja sąsiadujące dni o identycznym rozkładzie
+(`pon.–pt.`), ale **nie** zawija tygodnia przez granicę niedziela–poniedziałek: tydzień czyta się
+liniowo i zawijanie byłoby mylące.
+
+Testy: `packages/angular/map/src/core/*.test.ts` (`node --test`).
+
+## Grupowanie — jak działa i czego nie robi
+
+Siatka w przestrzeni pikseli: punkty rzutowane na piksele świata dla aktualnego zoomu
+i przypisane do komórek `gridSize` px. Algorytm jest O(n) i deterministyczny — ten sam
+zestaw danych zawsze daje te same grupy o tych samych identyfikatorach.
+
+Środek grupy uśredniamy **w pikselach, nie w stopniach**: Mercator rozciąga stopnie ku
+biegunom, więc średnia w stopniach wypada obok wizualnego środka kropek na ekranie.
+
+Ograniczenia (świadome):
+- grupa może „przeskoczyć" przy przekroczeniu granicy komórki podczas zoomowania — to cena
+  za brak preprocessingu, jaki wymaga clustering hierarchiczny;
+- **nie ma spiderfy.** Punkty o identycznej współrzędnej zostaną razem na każdym zoomie,
+  więc kliknięcie takiej grupy otwiera popup z listą pozycji zamiast zoomować w nieskończoność
+  (`isSplittable()` rozpoznaje ten przypadek);
+- powyżej `clusterMaxZoom` (domyślnie 16) grupowanie jest wyłączone.
+
+## Kafle — polityka OSM
+
+Domyślne `https://tile.openstreetmap.org/{z}/{x}/{y}.png` to usługa **best-effort bez SLA**.
+Fundacja OSM wymaga widocznej atrybucji i sensownego `User-Agent`/`Referer`, zabrania
+pre-fetchowania i zastrzega sobie blokowanie ruchu bez uprzedzenia — w szczególności
+komercyjnego. Domyślne źródło jest po to, żeby demo działało od razu.
+
+**Do produkcji podstaw własny lub komercyjny serwer kafli** przez `[tileUrl]` + `[attribution]`.
+Atrybucji nie usuwaj — to wymóg licencyjny, nie ozdoba.
+
+## Tokeny
+
+`--kpt-map-bg`, `--kpt-map-border`, `--kpt-map-radius`, `--kpt-map-popup-bg`,
+`--kpt-map-popup-shadow`, `--kpt-map-popup-width`, `--kpt-map-popup-width-card`,
+`--kpt-map-popup-max-height`, `--kpt-map-search-width`, `--kpt-map-search-panel-max-height`,
+`--kpt-map-poi-media-radius`, `--kpt-map-poi-row-hover`,
+`--kpt-map-cluster-bg`, `--kpt-map-cluster-fg`, `--kpt-map-marker-size`,
+`--kpt-map-height` (z `[height]`).
+
+Kolory znaczników i grup biorą się z ról kategorii: `--kpt-color-{success,warning,danger,
+info,primary,muted}` i ich warianty `-contrast`.
+
+## Kontekst układania Leafleta — nie ruszać
+
+`.kpt-map .leaflet-container` dostaje `z-index: 0`, żeby zamknąć skalę z-index Leafleta
+(panes 200–700, kontrolki 800) we własnym kontekście układania. Bez tego panes konkurują
+bezpośrednio z warstwą Angulara rozpiętą nad mapą — a popup (`z-index: 3`), kontrolki zoomu
+(2) i menu prawego przycisku (4) przegrywają i są **malowane pod kaflami**.
+
+Usterka jest podstępna, bo hit-test jej nie pokazuje: panes i kafle mają `pointer-events: none`,
+więc `document.elementFromPoint` zwraca popup jako element na wierzchu, mimo że użytkownik go
+nie widzi. Jedyny wiarygodny test to zrzut ekranu.
+
+Skala warstwy Angulara nad mapą: kontrolki zoomu `2`, popup `3`, menu prawego przycisku `4`,
+wyszukiwarka `5` (rozwinięty panel podpowiedzi ma zakrywać wszystko powyższe).
+
+## Mapa nie stylizuje hostów komponentów potomnych — nie „upraszczać"
+
+Wyszukiwarkę pozycjonuje **opakowanie** `<div class="kpt-map__search">`, a nie klasa
+postawiona wprost na `<kpt-map-search>`. Skrócenie tego do jednego elementu wygląda
+niewinnie i **chowa pole całkowicie**.
+
+Powód: host wyszukiwarki ma własną regułę `.kpt-map-search { position: relative }` (blok
+zawierający dla panelu podpowiedzi, potrzebny też poza mapą). Obie reguły trafiają wtedy na ten
+sam element z identyczną specyficznością (0,1,0) i w tej samej warstwie `kpt.components`, więc
+rozstrzyga kolejność wstrzyknięcia — a Angular wstrzykuje style dziecka **po** stylach rodzica.
+`position: relative` wygrywa z `absolute`, pole wypada do normalnego przepływu za
+`.kpt-map__canvas` (`height: 100%`) i zostaje przycięte przez `overflow: hidden` widoku.
+
+Usterka jest podstępna z tego samego powodu co ta z z-indexem: w DOM element jest, ma poprawne
+atrybuty i przechodzi każdą kontrolę „czy się wyrenderował". Widać ją wyłącznie na zrzucie ekranu.
+
+`class="kpt-map__legend"` na `<kpt-map-legend>` jest bezpieczne, bo `map.component.scss`
+**nie ma dla tej klasy żadnej reguły** — to czysty hak do zaczepienia z zewnątrz. Reguła
+dopisana tam kiedykolwiek w przyszłości wpadnie w tę samą pułapkę.
+
+## Odstępstwo od `@layer` — nie „naprawiać"
+
+`map.component.scss` ma dwie części: style własne w `@layer kpt.components` oraz sekcję
+nadpisań `.leaflet-*` **poza warstwą**. To jedyne takie miejsce w bibliotece i jest celowe:
+`leaflet.css` dostarcza aplikacja i nie jest warstwowany, a CSS spoza warstw wygrywa
+z każdą regułą w `@layer` **niezależnie od specyficzności**. Przeniesienie tych reguł
+do warstwy „dla porządku" sprawi, że przestaną działać.
+
+## A11y
+
+- znacznik: `role="img"` + `aria-label` = `title` lokalizacji,
+- grupa: `aria-label` = `map.cluster` z liczbą,
+- legenda: `role="group"`, pozycje jako `<button aria-pressed>`,
+- popup: `role="dialog"` z `aria-label` = tytuł; zamyka `Esc`, kliknięcie w mapę i przycisk ×
+  (w `popupLayout="card"` krzyżyk daje karta, żeby nie było dwóch),
+- karta miejsca: tytuł jako `role="heading" aria-level="3"`, kontakty jako `<ul>`/`<li>`,
+  godziny jako disclosure z `aria-expanded` i `aria-controls`, potwierdzenie kopiowania
+  przez `aria-live="polite"`,
+- wyszukiwarka: `role="combobox"` + `aria-expanded`/`aria-controls`/`aria-autocomplete="list"`,
+  lista jako `<ul role="listbox">` / `<li role="option">`, aktywna pozycja przez
+  `aria-activedescendant` (panel stoi w DOM obok pola, więc fokus zostaje w `<input>`),
+  klawiatura ↑/↓/Enter, pierwszy Esc zamyka listę, drugi czyści pole; liczba wyników
+  i „brak wyników" idą w `aria-live="polite"`,
+- kontrolki zoomu i „wyśrodkuj na mnie": `<button>` z `aria-label` ze słownika,
+- menu prawego przycisku: `role="menu"` / `role="menuitem"`.
+
+## i18n
+
+Klucze `map.*` w `KptMessages` (EN + PL): `addLocation`, `chooseCategory`, `myLocation`,
+`locateMe`, `locationDenied`, `locationUnavailable`, `zoomIn`, `zoomOut`, `legend`,
+`showCategory`, `hideCategory`, `cluster`, `clusterItems`, `fieldRequired`, `latitude`,
+`longitude`, `empty`, `save`, `cancel`, `lookingUpAddress`, `addressNotFound`.
+
+Wyszukiwarka: `map.search.*` — `placeholder`, `label`, `results`, `clear`, `noResults`,
+`minLength` ({count}), `searching`, `found` ({count}).
+
+Karta miejsca: `map.poi.*` — `distanceAway`, `openNow`, `closedNow`, `opensAt`, `closesAt`,
+`alwaysOpen`, `openingHours`, `closedDay`, `call`, `sendEmail`, `openWebsite`, `coordinates`,
+`copy`, `copied`, `share`, `addFavourite`, `removeFavourite`, `noPhoto`.
+
+Nowe pola formularza: `map.field.*` — `invalidEmail`, `invalidUrl`, `imageTooLarge`, `pickImage`,
+`orPasteUrl`, `removeImage`, `imagePreview`, `hoursClosed`, `hoursFrom`, `hoursTo`,
+`hoursSameAllWeek`, `hoursAddRange`, `hoursRemoveRange`, `hoursIncomplete`.
+
+Nazw dni tygodnia w słowniku **nie ma** — bierze je `Intl.DateTimeFormat` z locale, więc karta
+i edytor godzin działają dla dowolnego języka bez dopisywania tłumaczeń.
+
+## Przykład
+
+    // main.ts
+    bootstrapApplication(App, {
+      providers: [provideKptTablerIcons(), provideKptLeafletMap()],
+    });
+
+    // komponent
+    readonly locations = signal<KptMapLocation<Site>[]>(SITES);
+    readonly categories: KptMapCategory[] = [
+      { id: 'opening', label: 'Otwarcie', color: 'success', icon: 'building-store', fields: [ … ] },
+      { id: 'closure', label: 'Zamknięcie', color: 'danger', icon: 'lock', fields: [ … ] },
+    ];
+
+    onCreate(event: KptMapCreateEvent): void {
+      this.locations.update((all) => [...all, toLocation(event)]);
+    }
+
+    // szablon
+    <kpt-map
+      [locations]="locations()"
+      [categories]="categories"
+      country="PL"
+      allowCreate
+      showUserLocation
+      (locationCreate)="onCreate($event)"
+    >
+      <ng-template kptMapPopup category="opening" let-loc let-d="data">
+        <strong>{{ loc.title }}</strong>
+        <p>Otwarcie: {{ d.openingDate }}</p>
+      </ng-template>
+    </kpt-map>