@konce-pt/angular 0.7.11 → 0.7.12

package/map/src/lib/llms.txt

@@ -1,153 +1,153 @@
 # 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.
+A map with configurable markers: categories carrying a color and an icon, clustering with a count,
+a details popup whose template depends on the category, a ready-made place card, a legend, an address
+search and adding locations with the right mouse button. The default engine is Leaflet + OpenStreetMap; the component's API
+knows nothing about the engine, so a second adapter (Google Maps) swaps in through the provider alone.
 
 Import: `import { KptMap, KptMapPoiCard, KptMapSearch } from '@konce-pt/angular/map';`
 
-## Wymagania (aplikacja)
+## Requirements (the application)
 
-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".
+What follows is for the default engine, Leaflet. The alternative — Google Maps — needs no package
+and no stylesheet, but it does need an API key and a `mapId`; see the "Engines" section.
 
-1. Zależność **opcjonalna** `leaflet` — biblioteka jej nie instaluje:
+1. The **optional** `leaflet` dependency — the library does not install it:
 
        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):
+2. Leaflet's stylesheet — like `@angular/cdk/overlay-prebuilt.css`, through `angular.json → styles[]`,
+   NOT as an `import` in `main.ts` (the Angular CLI would turn that into an orphaned chunk):
 
        node_modules/leaflet/dist/leaflet.css
 
    Vite/webpack: `import 'leaflet/dist/leaflet.css';`
 
-3. Provider silnika w bootstrapie:
+3. The engine provider at bootstrap:
 
        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ą.
+Without the `leaflet` package installed the component still compiles and imports without error —
+only an attempt to render the map ends with a readable message and instructions.
+Leaflet is loaded with a dynamic `import()`, so it does not weigh down applications that use no map.
 
-## Selektor
+## Selector
 
-`kpt-map` — element blokowy. Wysokość ustawia `[height]` (domyślnie `480px`).
+`kpt-map` — a block element. The height is set by `[height]` (default `480px`).
 
-## Wejścia
+## Inputs
 
-- `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`
+- `locations`: `readonly KptMapLocation<T>[]` — **required**
+- `categories`: `readonly KptMapCategory[]` — **required**
+- `country`: `string` = `'PL'` — the initial view preset; an unknown code falls back to Poland
+- `view`: `{ center, zoom } | null` — an explicit view; overrides `country`
+- `bounds`: `KptMapBounds | null` — explicit bounds; override `country` and `view`
+- `restrictToCountry`: `boolean` = `false` — blocks panning outside the country's bounds/`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
+- `clusterOptions`: `{ gridSize?, maxZoom?, minPoints? }` — `60 / 16 / 2` by default
+- `clusterColorBy`: `'dominant' | 'none'` = `'none'` — whether a cluster takes the color of its most numerous category
+- `legend`: `boolean` = `true` — renders `kpt-map-legend` below the map
+- `legendCounts`: `boolean` = `true` — counters next to the legend entries
 - `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`"
+- `followUser`: `boolean` = `false` — recenters the map on every new position
+- `allowCreate`: `boolean` = `false` — an "Add location" menu under the right mouse button
+- `search`: `boolean` = `false` — the address search in the map's corner; it requires the
+  `KPT_MAP_GEOCODER` port **with a `search()` method**, and without it the field does not render
+- `searchPlaceholder`: `string` = `''` — an empty value hands it over to the dictionary
+- `searchOptions`: `{ minLength?, debounce?, limit?, countryCodes? }` — `3 / 300 / 5` by default
+- `searchZoom`: `number` = `16` — the zoom for a result with no bounds of its own
+- `searchMarker`: `boolean` = `true` — a temporary pin at the found point
+- `geocoder`: `KptMapGeocoderPort | null` = `null` — **this** map's geocoder; it wins over
+  `KPT_MAP_GEOCODER` from DI and serves both directions: the search and the address suggestions
+  in the create form
+- `popupLayout`: `'plain' | 'card'` = `'plain'` — `card` hands the popup over to the content entirely:
+  no padding, wider (`--kpt-map-popup-width-card`), scrolling once it exceeds
+  `--kpt-map-popup-max-height`, and no built-in close button (the card supplies one)
+- `distanceFrom`: `KptLatLng | null` = `null` — the reference point for the distance handed
+  to the popup template; `null` means "the user's position from `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")
+- `tileUrl`: `string | null` — OSM tiles by default (see "Tiles" below); **irrelevant for the Google engine**
+- `attribution`: `string | null` — `© OpenStreetMap contributors` by default; likewise
+- `engine`: `KptMapEngineFactory | null` — this map's engine; it wins over `KPT_MAP_ENGINE` from DI
+  (see "Engines")
 
-## Model / zdarzenia
+## Model / events
 
-- `hiddenCategories`: `model<string[]>` — identyfikatory kategorii ukrytych w legendzie
+- `hiddenCategories`: `model<string[]>` — the ids of categories hidden in the legend
 - `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
+- `locationCreate`: `{ at, categoryId, value }` — the component appends **nothing** to `locations`;
+  the application is the source of truth
+- `searchSelect`: `KptMapSearchResult` — a suggestion was picked; the map has **already** moved the view itself
+- `viewChange`: `{ center, zoom, bounds }` — after the map's movement ends
 - `userPositionChange`: `KptMapUserPosition | null`
 - `userLocationError`: `KptMapGeolocationError`
 
 ## KptMapCategory
 
-    { id: 'closure', label: 'Zamknięcie', color: 'danger', icon: 'lock',
+    { id: 'closure', label: 'Closure', 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.
+`color` is a role from the semantic layer (`primary | success | warning | danger | info | muted`)
+or a ready `var(--kpt-*)`. Literals (`#c00`, `rgb(...)`) are blocked at the type level —
+the repo's contract requires tokens.
 
-Rola daje **trzy** zmienne, zależnie od tego, czym element jest:
+A role yields **three** variables, depending on what the element is:
 
-| funkcja | do czego | `muted` daje |
+| function | for what | `muted` gives |
 |---|---|---|
-| `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` |
+| `colorVarOf()` | a background (a pin, a legend dot, a cluster) | `--kpt-color-muted` (neutral-100) |
+| `contrastVarOf()` | a glyph **on** that background | `--kpt-color-on-muted` (neutral-800) |
+| `foregroundVarOf()` | a glyph standing straight on the surface, with no background | `--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`.
+Getting it wrong only hurts with `muted`, because it is the only role whose `--kpt-color-*` is a background
+color rather than a content one — the rest are saturated and read fine in either function. Hence the third function:
+the place card paints the category icon straight onto the card's background, and `colorVarOf()` would give it
+neutral-100 on white. `icon` is a name from `KptIconRegistry` (the full Tabler set comes with
+`provideKptTablerIcons()`). `shape`: `pin` (the default, anchored at the tip), `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.
+`title` is required — it goes into the marker's `aria-label`. `data` is arbitrary and is handed
+to the popup template.
 
-## Szablony
+## Templates
 
-`kptMapPopup` — popup szczegółów, wybierany po kategorii. Szablon bez atrybutu `category`
-jest wariantem zapasowym; bez żadnego szablonu komponent pokazuje tytuł i nazwę kategorii.
+`kptMapPopup` — the details popup, chosen by category. A template with no `category` attribute
+is the fallback; with no template at all the component shows the title and the category name.
 
     <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>
+        <p>Closure · {{ d.status }}</p>
+        <kpt-button size="sm" (click)="openCard(loc)">Open the project card</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()`.
+Context: `$implicit` = the location, `data` = `location.data` (typed `T | undefined`, because `data`
+is optional), `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.
+`distance` is the point's distance in **meters** from `[distanceFrom]`, or from the user's position
+without it. `null` when there is no reference point — geolocation is disabled or was refused.
+Format it with `formatDistance(meters, locale)` from the core; `kpt-map-poi-card` does it itself.
 
-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):
+The type of `data` is loose by default — Angular does not carry the generic from `kpt-map` onto a directive
+embedded in its content. If you want inference, bind `[kptMapPopupTypeFor]` to the same array you feed
+the map (the input exists solely for that and is unused at runtime):
 
     <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).
+A popup opened near the container's edge pans the map so that it fits (auto-pan measures it
+after the first render — before that we do not know its dimensions).
 
-`kptMapCreateForm` — własny formularz dodawania. Jego obecność wyłącza formularz
-budowany ze schemy kategorii.
+`kptMapCreateForm` — your own create form. Its presence disables the form built
+from the category schema.
 
     <ng-template kptMapCreateForm let-api>
       <!-- api: { at, category, close(), submit(value) } -->
@@ -155,9 +155,9 @@ budowany ze schemy kategorii.
 
 ## 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.
+A ready-made place card for the popup: the distance, a 16:9 photo, a primary button + share + favorite,
+a category row, expandable opening hours with an open/closed status, and contact
+rows (phone, website, e-mail, coordinates) with actions and copy-to-clipboard.
 
     <kpt-map [locations]="places()" [categories]="categories" popupLayout="card">
       <ng-template kptMapPopup [kptMapPopupTypeFor]="places()"
@@ -167,139 +167,139 @@ kontaktowe (telefon, www, e-mail, współrzędne) z akcjami i kopiowaniem do sch
           [poi]="poiOf(loc, d)"
           [distance]="distance"
           [category]="category ?? null"
-          primaryLabel="Wyznacz trasę"
+          primaryLabel="Get directions"
           (primaryAction)="planRoute($event)"
           (closed)="close()"
         />
       </ng-template>
     </kpt-map>
 
-Wejścia:
+Inputs:
 
-- `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
+- `poi`: `KptMapPoi` — **required**
+- `distance`: `number | null` = `null` — meters; `null` hides the distance row
+- `category`: `KptMapCategory | null` = `null` — the icon, the color and the label of the category row
+- `primaryLabel`: `string` = `''` — an empty value hides the primary button
 - `showShare`, `showFavourite`, `closable`: `boolean` = `true`
 - `favourite`: `model<boolean>` = `false`
 - `hoursExpanded`: `model<boolean>` = `false`
 
-Wyjścia: `primaryAction: KptMapPoi`, `closed: void`, `shared: KptMapPoi`.
+Outputs: `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:
+`KptMapPoi` is **separate from the domain model** — the `location.data → KptMapPoi` mapping is done by
+the application. The library does not guess which field is the phone number:
 
     { 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:
+`photo` takes a URL or a `data:` string — the card does not tell them apart. Without one it draws a placeholder
+with an icon instead of collapsing the frame to zero. `facts` are arbitrary "icon · label · value" rows below the contacts.
+
+Behaviors worth remembering:
+
+- **The photo** sits in a 16:9 frame with `object-fit: cover` on a plain `<img>`, not on `kpt-image` —
+  that one is `inline-block` with `height: auto` and will not hold the frame.
+- **The hours** are a native disclosure (`aria-expanded` + `aria-controls`), not a `kpt-accordion`:
+  `KptAccordionPanel.title` accepts a plain string, while the header has to fit an icon, a colored
+  status and a chevron. The status is computed by `isOpenAt()`; days are joined by `groupWeek()`.
+- **The row actions** are always in the DOM. They are hidden only by `@media (hover: hover) and
+  (pointer: fine)`, and `:hover`/`:focus-within` reveals them — on touch and from the keyboard
+  they are available without any tricks.
+- **Copying** goes through `navigator.clipboard`; without that API the button does not render.
+  On success the icon changes to `check`, and a message goes to `aria-live`.
+- **Sharing** calls `navigator.share()`, and without it copies the address. The user canceling the sheet
+  is not an error and emits no `shared`.
+- **The title is a `<p role="heading" aria-level="3">`, not an `<h3>`.** Component styles live
+  in `@layer kpt.components`, and an application's CSS outside any layer always beats them — a plain
+  `<h3>` would catch every `h3 { … }` rule from the page's layout (in the playground that turned the place title
+  into 13-pixel uppercase). To a screen reader it is still a level 3 heading.
+- The card does not set its own `role` on the host — the `kpt-map` popup is already `role="dialog"`.
+
+Anatomy and scrolling:
 
     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
+      .kpt-map-poi__head      title + close button   — fixed
+      .kpt-map-poi__meta      distance + address     — fixed
+      .kpt-map-poi__scroll    photo, actions, category, hours, contacts, 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`.
+The header stays put, and only `__scroll` scrolls. The distance and the address belong to the header
+block, because they are part of the place's identity — to make them scroll with the content,
+just move `__meta` into `__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.
+The condition for this is that `popupLayout="card"` **hands scrolling to the card**: `.kpt-map__popup-body`
+then gets `display: flex` and `overflow: hidden`, and the card the popup's full height. As long as
+the parent container scrolls, the header cannot be pinned without `sticky` and negative margins.
+The popup itself does not get `overflow: hidden` — the `::after` arrow hangs at `top: 100%` and would be
+cut off. A card outside a popup (stories, any wrapper with no height limit) does not scroll
+at all: `__scroll` has `flex: 0 1 auto` and simply grows without a height ceiling.
 
-## Dodawanie lokalizacji
+## Adding locations
 
-Prawy klik → menu z kategoriami → `kpt-dialog` z formularzem. Domyślnie formularz powstaje
-z `category.fields` na Signal Forms. Typy pól i kontrolki:
+Right-click → a menu of categories → a `kpt-dialog` with a form. By default the form is built
+from `category.fields` on Signal Forms. Field types and controls:
 
-| `type` | kontrolka | uwagi |
+| `type` | control | notes |
 |---|---|---|
 | `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` |
+| `number` | `kpt-input-number` | `min`/`max` from the schema go through validators, not through `[min]` |
+| `date` | `kpt-datepicker` | `min`/`max` as ISO dates |
+| `select` / `multiselect` | `kpt-select` (`multiple`) | requires `options` |
+| `checkbox` | `kpt-checkbox` | `placeholder` serves as the label next to the field |
+| `tel` | `kpt-input type="tel"` | no format validation — phone numbers can be odd |
+| `email` | `kpt-input type="email"` | the `email()` validator |
+| `url` | `kpt-input type="url"` | the `https?://…` pattern |
+| `image` | `kpt-map-image-field` | a file picker **or** a pasted URL; the value is a `string` |
+| `hours` | `kpt-map-hours-field` | the value is a `KptMapOpeningHours` |
 
-Współrzędne z kliknięcia są pokazane, ale nieedytowalne.
+The coordinates from the click are shown but not editable.
 
-`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.
+`image` reads the file with `FileReader.readAsDataURL()` and **sends it nowhere** — the library knows
+nothing about the application's storage. The 2 MB limit is real, not decorative: a data URL swells by about a third,
+and the whole value travels in `locationCreate`. Typing a URL clears the chosen file and vice versa.
 
-`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`.
+`hours` gives seven rows starting on Monday (day names from `Intl`, not from the dictionary), two
+ranges per day, a "closed" marker and a "same all week" shortcut that copies
+Monday onto the rest. A day not marked as closed must have both times — otherwise
+the form is `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.
+The time is picked on a `kpt-datepicker selectionMode="time"` (a clock dial, `minuteStep=5`),
+not on a native `<input type="time">` — that one renders its own system dropdown, which
+cannot be styled and looks alien among the library's controls. The value is the same:
+`HH:mm` or an empty 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`.
+**A limitation:** with a dynamic schema the model is a `Record<string, unknown>`, so the fields
+are not statically typed. Anyone who needs types supplies their own `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.
+The "do not scare people with red on a fresh form" gate lives in the presentation (`touched() &&
+invalid()`), not in the validator — per this repo's Signal Forms contract.
 
-## Podpowiadanie adresu (geokodowanie wsteczne)
+## Address suggestions (reverse geocoding)
 
-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.
+The fields of the "add location" form can fill themselves in with the clicked point's address. Two conditions:
+the field has an `autofill` pointing at a part of the address, and the map has a port — from DI (`KPT_MAP_GEOCODER`)
+or from the `[geocoder]` input, which wins.
 
-    { key: 'city',    type: 'text', label: 'Miasto', autofill: 'city' },
-    { key: 'address', type: 'text', label: 'Adres',  autofill: 'address' },
+    { key: 'city',    type: 'text', label: 'City',    autofill: 'city' },
+    { key: 'address', type: 'text', label: 'Address', 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.
+The address parts (`KptMapAddressPart`): `street`, `houseNumber`, `address` (street with number),
+`city`, `postcode`, `state`, `county`, `country`, `countryCode`, `label` (the full address as one
+string). It works only for `text` and `textarea` fields — a date or a number will not take a fragment of an address.
 
-**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.
+**A suggestion never overwrites what the user typed** — only fields that are
+empty at the moment of the response are filled in. A missing port or a failed request does not block the form: the fields
+stay empty, and a note appears under the coordinates.
 
-Gotowy adapter (opt-in, NIE jest rejestrowany domyślnie):
+The ready adapter (opt-in, NOT registered by default):
 
     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`:
+**The Nominatim policy.** The public `nominatim.openstreetmap.org` instance allows at most
+one request per second, requires a recognizable `Referer`/`User-Agent` and forbids bulk
+querying; traffic can be blocked without notice, commercial traffic in particular. The adapter
+queues requests a second apart on its own and aborts them when the dialog closes, but for production
+put your own instance behind it (`baseUrl`) or a commercial provider through your own `KPT_MAP_GEOCODER`:
 
     export interface KptMapGeocoderPort {
       reverse(at: KptLatLng, options?): Observable<KptMapAddress | null>;
@@ -307,425 +307,425 @@ podstaw własną instancję (`baseUrl`) albo komercyjnego dostawcę przez własn
       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.
+Only `reverse()` is mandatory. Without `search()` the map shows no search field;
+`resolve()` is described below, with suggestions that carry no coordinates.
 
-**Odstęp między zapytaniami (`minIntervalMs`).** Sekunda nie jest cechą Nominatima, tylko
-wymogiem regulaminu **publicznej instancji OSM** — dlatego domyślna zależy od `baseUrl`:
+**The interval between requests (`minIntervalMs`).** The one-second gap is not a property of Nominatim, it is a
+requirement of the **public OSM instance's** terms — which is why the default depends on `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.
+On your own server there is nothing to respect, and for as-you-type suggestions a one-second
+delay is the difference between "it works" and "it stutters". `0` also removes the queuing — the requests
+go out in parallel. When pointing at **someone else's shared** instance, set the value explicitly.
 
-Testy i Storybook: `provideKptMapGeocoderStub({ city: 'Warszawa', address: 'Marszałkowska 100' })`.
+Tests and Storybook: `provideKptMapGeocoderStub({ city: 'Warszawa', address: 'Marszałkowska 100' })`.
 
-## Wyszukiwarka adresów (geokodowanie wprost)
+## Address search (forward geocoding)
 
-`[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.
+`[search]` puts a field with suggestions in the map's top right corner. Typing a phrase queries
+the geocoder port — the **same** one as the address suggestions in the create form, just
+in the other direction; from DI (`KPT_MAP_GEOCODER`) or from the `[geocoder]` input, which wins.
+The `search()` method is **optional** in the port: ports written before it existed still
+compile, and a map without it simply does not render the field.
 
     <kpt-map [locations]="places()" [categories]="categories" search
              (searchSelect)="onFound($event)" />
 
-    // main.ts — bez tego pola nie będzie
+    // main.ts — without this there will be no field
     providers: [provideKptLeafletMap(), provideKptNominatimGeocoder({ language: 'pl' })]
 
-Dwa typy, celowo rozdzielone:
+Two types, deliberately kept apart:
 
-    KptMapSuggestion   = { id, label, at?, bounds?, address? }   // pozycja na liście
-    KptMapSearchResult = KptMapSuggestion & { at: KptLatLng }    // to, co wychodzi ze zdarzenia
+    KptMapSuggestion   = { id, label, at?, bounds?, address? }   // an entry in the list
+    KptMapSearchResult = KptMapSuggestion & { at: KptLatLng }    // what comes out of the event
 
-`address` to ten sam `KptMapAddress`, co przy geokodowaniu wstecznym — nie ma drugiego modelu adresu.
+`address` is the same `KptMapAddress` as in reverse geocoding — there is no second address model.
 
-### Podpowiedzi bez współrzędnych (`resolve()`)
+### Suggestions with no coordinates (`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.
+Most geocoders queried forward (Nominatim, Photon, the Google Geocoding API) give `lat`/`lng`
+right in the list. **Google Places Autocomplete does not**: it returns a `placeId` and text,
+and the coordinates come from a separate Place Details call. This is not one provider's quirk — it is what
+its session-based billing rests on, where a whole run of suggestions plus the final Place Details counts
+as one event.
 
-Dlatego `search()` zwraca `KptMapSuggestion` (z `at` **opcjonalnym**), a port może dopisać:
+That is why `search()` returns a `KptMapSuggestion` (with `at` **optional**), and a port may add:
 
     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.
+The rule fits in one sentence: **if your `search()` does not return `at`, you must implement
+`resolve()`.** Anyone returning coordinates right away does not need the method — the field will not even call it.
 
-Obsługa siedzi w `kpt-map-search`, nie w `kpt-map`, więc gwarancja obowiązuje tak samo przy polu
-postawionym samodzielnie:
+The handling lives in `kpt-map-search`, not in `kpt-map`, so the guarantee holds just the same for a field
+standing on its own:
 
-- 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.
+- a suggestion with `at` → `selected` fires **immediately**, with no extra request;
+- a suggestion without `at` → `resolve()` once, **after the entry is picked**, never while typing;
+  the panel stays open with a "Searching…" note, and `aria-busy` on the field carries that to a screen reader;
+- `null` or an error → the label stays in the field, the list comes back (another entry can be picked),
+  and `aria-live` says "no matching places";
+- another pick or clearing the field aborts an in-flight request.
 
-**`selected` i `searchSelect` zawsze niosą współrzędne.** Aplikacja nigdy nie sprawdza, czy `at` jest.
+**`selected` and `searchSelect` always carry coordinates.** The application never checks whether `at` is there.
 
-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.
+When a port **has no** `resolve()`, suggestions without `at` never reach the list at all: an entry whose
+click would have nowhere to fly is worse than no entry.
 
-Atrapa umie udawać takiego dostawcę — bez tego ścieżki nie da się pokazać bez klucza API:
+The stub can pretend to be such a provider — without it there is no way to demo the path without an API key:
 
     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.
+**After a suggestion is picked the map moves the view itself.** A result with `bounds` (a city, a region,
+a province) gets `fitBounds`, and a result without them — `setView` at `[searchZoom]`. The
+`searchSelect` event fires after the movement and is there for the application's own purposes (moving
+`[distanceFrom]`, querying for nearby points), not for navigation.
+
+The Nominatim adapter **deliberately rejects an overly tight box** and returns the point alone in that case.
+A single address has a bounding box on the order of 0.0001° there, so `fitBounds` would jump to
+the top zoom limit on it and every address would land at a different zoom, depending on how
+the provider traced the building — with the threshold, addresses land at a repeatable `[searchZoom]`,
+while cities still fit into the frame whole.
+
+The rule is held by `isFittableBounds(bounds, minSpan?)` from the core (`KPT_MIN_FIT_SPAN` = 0.001°,
+that is ~100 m) — it is in the public API, it has tests and it applies to every adapter, not just Nominatim.
+The threshold only has to be exceeded on **one** axis: a long, narrow street has one microscopic dimension
+and still deserves `fitBounds`.
+
+**Geographic narrowing.** The query gets a `viewbox` from `[bounds]`, or from the `[country]`
+preset without them — that is bias only, it reorders the results and cuts nothing off. A hard
+`countrycodes` is only added with `restrictToCountry` (the map will not let the view move
+outside the country anyway, so a foreign address would be impossible to show) or explicitly
+through `searchOptions.countryCodes`.
+
+**The temporary pin** (`[searchMarker]`, on by default) travels the same path as the other
+markers — through `engine.setMarkers()` — so it moves with the map frame by frame.
+It does not belong to `entries()`, so clicking it opens nothing. It disappears once the field
+is cleared with the × and after a click on the map.
+
+The Nominatim policy is **stricter here than for `reverse()`**, because as-you-type suggestions
+generate series of requests by their nature. The adapter defends itself two ways: the field waits
+a `debounce` (300 ms) after the last character and does not query below `minLength` (3 characters), while the
+adapter itself keeps **one queue shared with `reverse()`** — one request per second for the whole
+client, not per method. An abandoned request (another character, the field closing) is aborted with
+an `AbortController`. For production, put your own instance or a commercial provider behind it anyway.
+
+The queue measures the interval **against the clock** rather than adding a fixed delay before each request: the first one
+after a quiet moment goes out immediately, and the next waits only for what is left of the second.
+The upper bound of one request per second stays intact, but the first suggestion
+no longer costs a second up front.
 
 ### 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):
+The field itself is a separate component — like the legend, so that it can stand outside the map
+(an application toolbar, a side panel):
 
     <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.
+Inputs: `placeholder`, `minLength` (3), `debounce` (300), `limit` (5), `countryCodes`,
+`viewbox`, `disabled`, `geocoder` (this field's port; it wins over DI — that is how
+`kpt-map` passes it in). Outputs: `selected: KptMapSearchResult`, `cleared: void`.
+Without a port that has `search()` the field renders **disabled**, rather than pretending it will find anything.
 
-**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.
+**Why not `kpt-autocomplete`** — the question keeps coming back, so in writing: that one filters options
+client-side (`includes(q)`), so a geocoder result that tolerates typos or is phrased differently
+would drop off the list; its value is a plain `string`, so there is nothing to carry
+coordinates in; and it stands on CDK Overlay, which would add `@angular/cdk/overlay-prebuilt.css`
+to the map's requirements when it otherwise needs none. The suggestion panel is therefore drawn directly
+in the Angular layer over the map, just like the popup and the right-click menu.
 
-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`).
+The debounce stands on a `setTimeout` inside an effect with `onCleanup`, not on rxjs operators: this package's
+ports use `Observable`/`of` exclusively, and rxjs is not declared as the library's
+`peerDependency` (it arrives transitively through `@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.
+The typed text and the phrase to query are **two separate signals**. Picking a suggestion writes its
+label into the field but does not touch the phrase — otherwise a pick would immediately fire another query
+for what we just found.
 
-## Legenda
+## Legend
 
-`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` — a separate component, so that it can be placed outside the map. The entries are
+buttons with `aria-pressed`; a click hides the category (it also disappears from the clusters, and the counters drop).
 
     <kpt-map [legend]="false" [(hiddenCategories)]="hidden" … />
     <kpt-map-legend [categories]="categories" [(hidden)]="hidden" orientation="vertical" />
 
-Wejścia: `categories` (wymagane), `hidden` (model), `counts`, `orientation`, `interactive`.
+Inputs: `categories` (required), `hidden` (a model), `counts`, `orientation`, `interactive`.
 
-## Geolokalizacja
+## Geolocation
 
-`[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:
+`[showUserLocation]` enables the marker for the user's own position (the `user` icon) with an accuracy circle
+and a "center on me" control. The position comes through a DI port:
 
-    KPT_MAP_GEOLOCATION → KptBrowserGeolocation (domyślnie)
-    provideKptMapGeolocationStub({ lat: 52.23, lng: 21.01 })   // Storybook, testy
+    KPT_MAP_GEOLOCATION → KptBrowserGeolocation (by default)
+    provideKptMapGeolocationStub({ lat: 52.23, lng: 21.01 })   // Storybook, tests
 
-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`.
+The Geolocation API works **only in a secure context** (HTTPS or `localhost`).
+On `http://` with an IP address the browser refuses — that is not a bug in the component. A denied permission
+disables the control and emits `userLocationError`; the component shows no alert of its own, leaving
+the decision about a message to the application. Under SSR the port returns `null`.
 
-## Silniki
+## Engines
 
-Silnik dostarcza fabryka pod tokenem `KPT_MAP_ENGINE`, a komponent rozmawia z nią przez
-interfejs `KptMapEngine` (zero typów Leafleta w sygnaturach). Podział renderowania:
+The engine is supplied by a factory under the `KPT_MAP_ENGINE` token, and the component talks to it through
+the `KptMapEngine` interface (zero Leaflet types in the signatures). The split of rendering:
 
-- kafle, panning, zoom, **znaczniki i grupy** → silnik (`L.divIcon` z HTML-em z rdzenia),
-- **popup, kontrolki, menu, legenda, dialog** → warstwa Angulara nad kontenerem mapy.
+- tiles, panning, zoom, **markers and clusters** → the engine (`L.divIcon` with HTML from the core),
+- **the popup, the controls, the menu, the legend, the dialog** → an Angular layer over the map container.
 
-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.
+Markers go through the engine because they have to move with the map frame by frame (Leaflet does that
+with a single `transform` on the pane). There is one popup at a time, so recomputing its position
+with `engine.project()` on every movement is cheap — and it buys full Angular in the content
+and one implementation for both engines.
 
-### Dwa silniki
+### Two engines
 
-    provideKptLeafletMap()                              // domyślny, bez klucza i konta
-    provideKptGoogleMap({ apiKey, mapId })              // Google Maps JavaScript API
+    provideKptLeafletMap()                              // the default, no key and no account
+    provideKptGoogleMap({ apiKey, mapId })              // the 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 needs the (optional) `leaflet` package and `leaflet/dist/leaflet.css`. Google needs
+**no npm package at all** — the API is pulled in by a script with the first map — but it does need a key,
+a billing account with a card and a `mapId` from the console (*Map management → Create Map ID*).
+Without `mapId` `AdvancedMarkerElement` does not work, which means there will be no markers.
 
 |                        | `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            |
+| `[tileUrl]`/`[attribution]` | work, swappable on the fly | **ignored** — Google supplies the tiles     |
+| attribution            | Leaflet's control (ODbL)      | the logo and ToS links are built in, **do not cover them** |
+| key / account          | not needed                    | an API key + billing with a card           |
+| cost                   | OSM tiles (no SLA)            | the Dynamic Maps SKU: 10k loads/month free |
+| the Google geocoder    | **not allowed**               | allowed                                    |
+| zoom                   | integer, max 19               | fractional on gestures, above 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.
+**The last row is the reason this engine exists.** The Google Maps Platform Service
+Specific Terms §6.2 (Geocoding API) and §14.2 (Places API) forbid using their results
+"in conjunction with a non-Google map". A Google adapter under `KPT_MAP_GEOCODER` is therefore compliant
+**only** with the `google` engine — not with the default Leaflet. The library itself
+ships no such adapter; that is the application's decision and code.
 
-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.
+That is why the geocoder is per map rather than per application: the `[geocoder]` input (below) lets you
+put a Leaflet map with an OSM geocoder next to a Google map with a Google geocoder.
+A global provider could not settle that — it would have to break the rule on one
+of the two sides.
 
-### `[engine]` — dwie mapy, dwa silniki, jedna strona
+### `[engine]` — two maps, two engines, one page
 
-Wejście przyjmuje fabrykę i wygrywa nad `KPT_MAP_ENGINE` z DI. Bez niego nic się nie zmienia.
+The input takes a factory and wins over `KPT_MAP_ENGINE` from DI. Without it nothing changes.
 
     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`.
+It is read once, at initialization — swapping it after startup does not reload the map. No engine
+in either source produces a readable error with instructions, not a `NullInjectorError`.
 
-### `[geocoder]` — port idzie za silnikiem
+### `[geocoder]` — the port follows the engine
 
-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.
+Symmetrical to `[engine]` and for the same reason: a Google geocoder may only be shown
+with a Google map, and that is a property of the **map**, not of the application. The input wins over
+`KPT_MAP_GEOCODER` from DI and reaches both the search and the create form.
 
-    <kpt-map [engine]="leaflet" search … />                        <!-- port z DI (np. Nominatim) -->
+    <kpt-map [engine]="leaflet" search … />                        <!-- the port from DI (Nominatim, say) -->
     <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.
+Unlike `[engine]` it is read **reactively**: swapping the port clears the suggestion list
+and queries the new provider from the next phrase on. `null` in both sources means what
+having no port means today: the search field does not render, and the form suggests no address.
 
-To samo wejście ma `kpt-map-search` i `kpt-map-create-dialog`, gdy stoją poza mapą.
+`kpt-map-search` and `kpt-map-create-dialog` have the same input when they stand outside a 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:
+**When writing a Google adapter, go through the SDK, not through REST.** The
+`maps.googleapis.com/maps/api/geocode/json` web service rejects keys restricted by domain:
 
     { "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):
+and that is the only restriction that makes sense for a key sitting in plain sight in a browser bundle. CORS on
+that endpoint works, so there is not even a network error — a `200` arrives with `REQUEST_DENIED`
+in the body, easy to miss. `google.maps.Geocoder` from the loaded SDK authorizes the same way the map itself
+does, so it works with the same key — the same SKU, just a different route. Access to the API
+comes from the exported loader (the same one the engine uses):
 
     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`.
+Mind the shape of the response: the SDK returns `location` and `viewport` as objects with methods
+(`lat()`, `getNorthEast()`), not as fields the way REST does. An SDK request **cannot be aborted**,
+so the `signal` from the port's options has nothing behind it — unsubscribing merely stops listening.
+An adapter from start to finish: `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).
+The engine lands on the host as `[data-engine]` (`leaflet` | `google`) — that attribute is what the few
+differences are styled by, such as the accuracy circle (an SVG circle in Leaflet, an element with a background in
+Google, because `google.maps.Circle` takes colors in its options while tokens are the rule here).
 
-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.
+The Google adapter computes `project()`/`unproject()` **in the core** (`core/geo.ts`) rather than with
+`map.getProjection()`: that one can be `null` until the first `idle` and needs converting
+into container pixels anyway. As a result the popup lands pixel for pixel where it does with Leaflet,
+agrees with the clustering and copes with fractional zoom.
 
-## Rdzeń (pure TS)
+## Core (pure TS)
 
-`@konce-pt/angular/map` eksportuje rdzeń obliczeń — bez Angulara i bez silnika, przenośny
-do portu React: `clusterLocations`, `dominantCategory`, `countByCategory`, `isSplittable`,
+`@konce-pt/angular/map` exports the computation core — with no Angular and no engine, portable
+to the React port: `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`,
+`formatDistance`/`formatLatLng` and the opening hours: `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.
+The hours model: `KptMapOpeningHours` = an array of `{ day: 1–7 (ISO), closed?, ranges: [{ from, to }] }`
+in `HH:MM` of the place's local time. A `to` lower than or equal to `from` means "past midnight";
+`24:00` is a valid end of day and does **not** cross midnight. A missing day = closed.
+`isOpenAt()` checks two days — the current one and the previous one — because a `22:00–01:00` range covers
+the early hours of the next day. `groupWeek()` joins adjacent days with an identical schedule
+(`Mon–Fri`), but it does **not** wrap the week across the Sunday–Monday boundary: a week reads
+linearly and wrapping would be confusing.
 
-Testy: `packages/angular/map/src/core/*.test.ts` (`node --test`).
+Tests: `packages/angular/map/src/core/*.test.ts` (`node --test`).
 
-## Grupowanie — jak działa i czego nie robi
+## Clustering — how it works and what it does not do
 
-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.
+A grid in pixel space: points are projected onto world pixels for the current zoom
+and assigned to `gridSize` px cells. The algorithm is O(n) and deterministic — the same
+data set always yields the same clusters with the same ids.
 
-Ś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.
+The cluster center is averaged **in pixels, not in degrees**: Mercator stretches degrees toward the
+poles, so an average in degrees lands beside the visual center of the dots on screen.
 
-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.
+The limitations (deliberate):
+- a cluster can "jump" when a cell boundary is crossed while zooming — that is the price
+  for skipping the preprocessing hierarchical clustering requires;
+- **there is no spiderfy.** Points with identical coordinates stay together at every zoom,
+  so clicking such a cluster opens a popup listing the entries instead of zooming forever
+  (`isSplittable()` recognizes that case);
+- above `clusterMaxZoom` (16 by default) clustering is switched off.
 
-## Kafle — polityka OSM
+## Tiles — the OSM policy
 
-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.
+The default `https://tile.openstreetmap.org/{z}/{x}/{y}.png` is a **best-effort service with no SLA**.
+The OSM Foundation requires visible attribution and a sensible `User-Agent`/`Referer`, forbids
+pre-fetching and reserves the right to block traffic without notice — commercial traffic
+in particular. The default source is there so that the demo works right away.
 
-**Do produkcji podstaw własny lub komercyjny serwer kafli** przez `[tileUrl]` + `[attribution]`.
-Atrybucji nie usuwaj — to wymóg licencyjny, nie ozdoba.
+**For production, put your own or a commercial tile server behind it** through `[tileUrl]` + `[attribution]`.
+Do not remove the attribution — it is a license requirement, not decoration.
 
-## Tokeny
+## Tokens
 
 `--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]`).
+`--kpt-map-height` (from `[height]`).
 
-Kolory znaczników i grup biorą się z ról kategorii: `--kpt-color-{success,warning,danger,
-info,primary,muted}` i ich warianty `-contrast`.
+Marker and cluster colors come from the category roles: `--kpt-color-{success,warning,danger,
+info,primary,muted}` and their `-contrast` variants.
 
-## Kontekst układania Leafleta — nie ruszać
+## Leaflet's stacking context — do not touch
 
-`.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**.
+`.kpt-map .leaflet-container` gets `z-index: 0`, to close Leaflet's z-index scale
+(panes 200–700, controls 800) inside its own stacking context. Without that the panes compete
+directly with the Angular layer stretched over the map — and the popup (`z-index: 3`), the zoom controls
+(2) and the right-click menu (4) lose and are **painted under the tiles**.
 
-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.
+The bug is insidious, because a hit test does not show it: the panes and tiles have `pointer-events: none`,
+so `document.elementFromPoint` returns the popup as the topmost element even though the user
+cannot see it. The only reliable test is a screenshot.
 
-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).
+The scale of the Angular layer over the map: zoom controls `2`, the popup `3`, the right-click menu `4`,
+the search `5` (an expanded suggestion panel has to cover everything above).
 
-## Mapa nie stylizuje hostów komponentów potomnych — nie „upraszczać"
+## The map does not style child components' hosts — do not "simplify"
 
-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**.
+The search is positioned by a **wrapper**, `<div class="kpt-map__search">`, and not by a class
+placed directly on `<kpt-map-search>`. Shortening that to a single element looks
+innocent and **hides the field completely**.
 
-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.
+The reason: the search host has its own `.kpt-map-search { position: relative }` rule (the containing
+block for the suggestion panel, needed outside the map too). Both rules would then land on the
+same element with identical specificity (0,1,0) and in the same `kpt.components` layer, so
+injection order decides — and Angular injects a child's styles **after** the parent's.
+`position: relative` beats `absolute`, the field drops into normal flow behind
+`.kpt-map__canvas` (`height: 100%`) and is clipped by the view's `overflow: hidden`.
 
-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.
+The bug is insidious for the same reason as the z-index one: the element is in the DOM, has the right
+attributes and passes every "did it render" check. It only shows up in a screenshot.
 
-`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ę.
+`class="kpt-map__legend"` on `<kpt-map-legend>` is safe, because `map.component.scss`
+**has no rule for that class** — it is a pure hook for attaching things from outside. A rule
+added there at any point in the future would fall into the same trap.
 
-## Odstępstwo od `@layer` — nie „naprawiać"
+## A deviation from `@layer` — do not "fix" this
 
-`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ć.
+`map.component.scss` has two parts: its own styles in `@layer kpt.components` and a section
+of `.leaflet-*` overrides **outside the layer**. It is the only such place in the library and it is deliberate:
+`leaflet.css` is supplied by the application and is not layered, and CSS outside layers beats
+every rule inside `@layer` **regardless of specificity**. Moving those rules
+into the layer "for tidiness" will stop them from working.
 
 ## 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"`.
+- a marker: `role="img"` + `aria-label` = the location's `title`,
+- a cluster: `aria-label` = `map.cluster` with the count,
+- the legend: `role="group"`, entries as `<button aria-pressed>`,
+- the popup: `role="dialog"` with `aria-label` = the title; closed by `Esc`, a click on the map and the × button
+  (with `popupLayout="card"` the card supplies the close button, so there are not two),
+- the place card: the title as `role="heading" aria-level="3"`, the contacts as `<ul>`/`<li>`,
+  the hours as a disclosure with `aria-expanded` and `aria-controls`, copy confirmation
+  through `aria-live="polite"`,
+- the search: `role="combobox"` + `aria-expanded`/`aria-controls`/`aria-autocomplete="list"`,
+  the list as `<ul role="listbox">` / `<li role="option">`, the active entry through
+  `aria-activedescendant` (the panel sits in the DOM next to the field, so focus stays in the `<input>`),
+  the ↑/↓/Enter keys, the first Esc closes the list, the second clears the field; the result count
+  and "no results" go to `aria-live="polite"`,
+- the zoom controls and "center on me": `<button>` with an `aria-label` from the dictionary,
+- the right-click menu: `role="menu"` / `role="menuitem"`.
 
 ## i18n
 
-Klucze `map.*` w `KptMessages` (EN + PL): `addLocation`, `chooseCategory`, `myLocation`,
+The `map.*` keys in `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`,
+The search: `map.search.*` — `placeholder`, `label`, `results`, `clear`, `noResults`,
 `minLength` ({count}), `searching`, `found` ({count}).
 
-Karta miejsca: `map.poi.*` — `distanceAway`, `openNow`, `closedNow`, `opensAt`, `closesAt`,
+The place card: `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`,
+The newer form fields: `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ń.
+Weekday names are **not** in the dictionary — `Intl.DateTimeFormat` takes them from the locale, so the card
+and the hours editor work for any language without adding translations.
 
-## Przykład
+## Example
 
     // main.ts
     bootstrapApplication(App, {
       providers: [provideKptTablerIcons(), provideKptLeafletMap()],
     });
 
-    // komponent
+    // the component
     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: [ … ] },
+      { id: 'opening', label: 'Opening', color: 'success', icon: 'building-store', fields: [ … ] },
+      { id: 'closure', label: 'Closure', color: 'danger', icon: 'lock', fields: [ … ] },
     ];
 
     onCreate(event: KptMapCreateEvent): void {
       this.locations.update((all) => [...all, toLocation(event)]);
     }
 
-    // szablon
+    // the template
     <kpt-map
       [locations]="locations()"
       [categories]="categories"
@@ -736,6 +736,6 @@ i edytor godzin działają dla dowolnego języka bez dopisywania tłumaczeń.
     >
       <ng-template kptMapPopup category="opening" let-loc let-d="data">
         <strong>{{ loc.title }}</strong>
-        <p>Otwarcie: {{ d.openingDate }}</p>
+        <p>Opening: {{ d.openingDate }}</p>
       </ng-template>
     </kpt-map>