@konce-pt/angular 0.7.0 → 0.7.6

package/CHANGELOG.md

@@ -1,5 +1,385 @@
 # @konce-pt/angular
 
+## 0.7.6
+
+### Minor Changes
+
+- 1e20c5e: `kpt-badge` — nowe wejście `size` (`'sm' | 'md' | 'lg'`, domyślnie `'md'`).
+
+  Wysokość (`1rem` / `1.25rem` / `1.5rem`) steruje resztą geometrii: krój to `calc(--_size * 0.6)`,
+  wcięcie boczne i średnica kropki skalują się razem z nią. `md` wychodzi identycznie jak dotąd
+  (0.75rem kroju, kropka 0.65rem), więc istniejące użycia nie zmieniają wyglądu.
+
+  `sm` jest po to, żeby wstawić odznakę w wiersz tekstu — przy etykiecie, w pozycji menu, w komórce
+  tabeli — bez rozpychania wiersza.
+
+- 8dd8e41: `KptMenuItem` — wiersz nagłówkowy i odznaka na pozycji.
+
+  - `header: true` zamienia pozycję w nieklikalny blok tekstu: `avatar` (`{ src?, name?, icon? }`,
+    renderowany przez `kpt-avatar`), `label` w półgrubym kroju i `description` drugą linią. Pokrywa
+    oba typowe zastosowania nagłówka menu: dane zalogowanego użytkownika (nazwa + e-mail) i opis
+    funkcji menu. To `<div role="presentation">`, więc nie wchodzi do nawigacji klawiaturą i nie
+    narusza kontraktu dzieci `role="menu"`.
+  - `badge` (`string | number`) plus `badgeVariant` dokładają odznakę wyrównaną do prawej krawędzi
+    pozycji — licznik powiadomień, status. Renderuje ją `kpt-badge`, więc wartości powyżej `max`
+    skracają się do `99+`, a wartość wchodzi w nazwę dostępną pozycji.
+  - `description` działa też na zwykłych pozycjach — dwuwierszowa pozycja menu.
+
+  Pola honorują `kpt-menu`, `kpt-context-menu` i `kpt-split-button`. `kpt-menubar`, `kpt-megamenu`
+  i `kpt-speed-dial` dzielą typ, ale renderowania nie zmieniają. Wszystkie pola są opcjonalne —
+  istniejące `items` działają bez zmian.
+
+- d67fde2: `kpt-sidenav` — slot stopki `kptSidenavFooter` przyklejonej do dołu panelu.
+
+  Element z tym atrybutem trafia poza obszar przewijany, więc zostaje na dole niezależnie od długości
+  nawigacji — blok zalogowanego użytkownika, przełącznik motywu czy numer wersji nie odjeżdżają razem
+  z listą pozycji. Stopka dostaje górną kreskę na pełną szerokość panelu i ten sam padding co nawigacja.
+  W szynie ikon (`sidenavRailBreakpoint`) tekst stopki chowa się tym samym atrybutem `kptNavLabel`
+  co etykiety pozycji.
+
+  Wewnątrz komponentu `padding`, `gap` i `overflow-y` przeniosły się z hosta do obszaru przewijanego —
+  panele bez stopki wyglądają identycznie jak dotąd. Zmiana dotyka tylko aplikacji, które celowały
+  w `kpt-sidenav > *` selektorem dziecka bezpośredniego.
+
+### Patch Changes
+
+- Migotanie przycisków i paneli na pierwszej klatce — poprawki `kpt-button`, `kpt-drawer`
+  i `kpt-bottom-sheet`.
+
+  Wspólna przyczyna: reguły stylu warunkowane atrybutem `[attr.data-*]`, który Angular ustawia
+  dopiero w przebiegu aktualizacji. Przez jedną klatkę komponent stał więc w stanie bazowym
+  i dopiero potem animował się do właściwego.
+
+  - **Przyciski** — sprzężenie zwrotne hovera i aktywności niesie pseudoelement `::after`
+    (`opacity` 0 → 1) zamiast animowanego `background-color`. Warstwa startuje przezroczysta,
+    więc zmiana jej koloru na pierwszej klatce jest niewidoczna. `inset: 0` trzyma ją wewnątrz
+    ramki, dzięki czemu obrys wariantu `outline` zostaje widoczny pod kursorem. Ten sam wzorzec
+    dostają `kpt-icon-button`, `kpt-fab` i `kpt-split-button`.
+  - **`kpt-drawer`** — geometria pozycji domyślnej i przesunięcie poza ekran wróciły do reguły
+    bazowej, więc zamknięty panel nie pokazuje się na moment przed animacją.
+  - **`kpt-drawer` i `kpt-bottom-sheet`** — zamknięty panel wypada z kolejki Tab i z drzewa
+    dostępności przez `visibility: hidden`, nie przez `inert`. Jest poprawny już na pierwszej
+    klatce, bez czekania na JavaScript, a animacja wjazdu zostaje (czego `display: none`
+    by nie pozwolił).
+
+  Wszystkie trzy komponenty honorują teraz `prefers-reduced-motion: reduce`.
+
+## 0.7.5
+
+### Minor Changes
+
+- Responsywny `kpt-app-shell`: nakładka, szyna ikon i panel zadokowany
+
+  `kpt-app-shell` sam dobiera układ do szerokości okna. Nowy tryb `auto` (od `sidenavBreakpoint`,
+  domyślnie `lg`, panel jest zadokowany; poniżej — nakładka ze scrimem, domyślnie zamknięta),
+  opcjonalna szyna ikon w paśmie do `sidenavRailBreakpoint`, `Escape` zamykające nakładkę,
+  `inert` na treści pod nią, poprawny kierunek wysuwu w RTL i wysokość `100dvh`.
+
+  O układzie decyduje wyłącznie CSS, więc nic nie migocze przed hydracją i całość działa na SSR.
+
+  **Zmiana zachowania:** domyślną wartością `sidenavMode` jest teraz `'auto'` zamiast `'side'`.
+  Jeśli aplikacja sama zarządza responsywnością szkieletu (własne `@media` i własny hamburger),
+  ustaw jawnie `sidenavMode="side"` — inaczej dostaniesz dwie warstwy tej samej logiki.
+  Tryby `'side'` i `'over'` działają dokładnie jak wcześniej.
+
+  Nowe API:
+
+  - `KptBreakpointObserver` — media query jako sygnały (`up`, `down`, `matches`), spięte
+    z tokenami `--kpt-breakpoint-*`; poza przeglądarką zwraca `false`.
+  - `KptShellNavToggle` (`[kptShellNavToggle]`) — hamburger, który sam trafia w stan właściwy
+    dla bieżącego układu i dokłada `aria-expanded` / `aria-controls` / etykietę z i18n.
+  - `kpt-app-shell`: `sidenavCompactOpen`, `sidenavBreakpoint`, `sidenavRailBreakpoint`,
+    `sidenavLabel`, `sidenavId`, `isOverlay()`, `isSidenavOpen()`,
+    `toggleSidenav()` / `openSidenav()` / `closeSidenav()`.
+  - `kpt-toolbar`: input `wrap` (zawijanie zawartości) oraz kompaktowa wysokość poniżej `sm`.
+  - `@konce-pt/grid`: klasy `kpt-display-*` z wariantami per breakpoint i skrótem `kpt-hide`.
+  - Tokeny: `--kpt-sidenav-rail-width` (4rem), `--kpt-toolbar-height-compact` (3rem).
+  - Słownik: namespace `appShell` (`toggleNavigation`, `navigation`) w EN i PL.
+
+  Poprawka: `kpt-drawer` używał fallbacku `--kpt-z-overlay: 1000` (wartość `z.dropdown`)
+  zamiast `1100`.
+
+- Nowy komponent `KptMap` (kpt-map) w subpathu `@konce-pt/angular/map` — interaktywna mapa
+  z konfigurowalnymi znacznikami, na silniku Leaflet + OpenStreetMap.
+
+  - Kategorie obiektów z kolorem (rola semantyczna tokenów, nie literał) i ikoną z `KptIconRegistry`;
+    kształty `pin` / `dot` / `square`.
+  - Grupowanie znaczników z licznikiem — własny rdzeń pure TS (siatka w przestrzeni pikseli, O(n),
+    deterministyczna), wspólny dla obu silników i przenośny do portu React. Bez `leaflet.markercluster`.
+  - Popup szczegółów o szablonie zależnym od kategorii (`ng-template kptMapPopup`), renderowany
+    przez Angulara i pozycjonowany przez `engine.project()` — pełne komponenty `kpt-*` w treści.
+    Kontekst szablonu niesie też `distance` — odległość punktu w metrach od `[distanceFrom]`,
+    a bez niego od pozycji użytkownika.
+  - **Karta miejsca `KptMapPoiCard` (kpt-map-poi-card)**: dystans, zdjęcie 16:9, przycisk główny
+    z udostępnianiem i ulubionymi, wiersz kategorii, rozwijane godziny otwarcia ze statusem
+    otwarte/zamknięte i wiersze kontaktowe (telefon, www, e-mail, współrzędne) z kopiowaniem
+    do schowka. Sterowana danymi: bierze `KptMapPoi`, nie model domenowy aplikacji.
+  - `[popupLayout]="'card'"` oddaje popup w całości treści — bez paddingu, szerszy, przewijalny
+    i bez wbudowanego krzyżyka (daje go karta). Domyślne `plain` zostaje bez zmian.
+  - Nagłówek karty (tytuł, krzyżyk, dystans i adres) stoi nieruchomo; przewija się wyłącznie
+    reszta treści, w osobnym `.kpt-map-poi__scroll`. Przewijanie schodzi w tym celu z popupu
+    do karty — `popupLayout="card"` daje `.kpt-map__popup-body` `display: flex` i `overflow:
+hidden`, a karcie pełną wysokość. Sam popup zostaje bez `overflow: hidden`, bo ucięłby
+    strzałkę `::after` wiszącą na `top: 100%`. Karta poza popupem, bez limitu wysokości,
+    nie przewija się wcale.
+  - Pasek „Anuluj / Zapisz" w formularzu dodawania jest przypięty do dołu (`position: sticky`),
+    więc nie ucieka na koniec długiej listy pól.
+  - Legenda jako filtr: `KptMapLegend` (kpt-map-legend) z `aria-pressed`, liczniki per kategoria,
+    ukrycie kategorii usuwa ją także z grup.
+  - Dodawanie lokalizacji prawym przyciskiem myszy: formularz budowany ze schemy `category.fields`
+    na Signal Forms albo własny `ng-template kptMapCreateForm`. Poza `text`/`textarea`/`number`/
+    `date`/`select`/`multiselect`/`checkbox` schema przyjmuje `tel`, `email` i `url` (z walidacją
+    formatu), `image` — wybór pliku czytany jako `data:` **albo** wklejony adres, oraz `hours` —
+    edytor tygodnia dający `KptMapOpeningHours`.
+    Plik zdjęcia zostaje w przeglądarce: biblioteka nigdzie go nie wysyła i nie ma wiedzy
+    o storage'u aplikacji. Limit 2 MB jest realny — data URL puchnie o ~⅓, a cała wartość
+    leci w `locationCreate`.
+  - Widok startowy z presetu kraju (`KPT_MAP_COUNTRIES`, domyślnie Polska) oraz opcjonalne
+    ograniczenie przesuwania do jego zasięgu.
+  - Znacznik własnego położenia z geolokalizacji wraz z kręgiem dokładności i kontrolką
+    „wyśrodkuj na mnie"; źródło pozycji przez port DI `KPT_MAP_GEOLOCATION`
+    (`provideKptMapGeolocationStub()` dla Storybooka i testów).
+  - Silnik za interfejsem `KptMapEngine` — `provideKptLeafletMap()` dziś, adapter Google Maps
+    bez zmian w API komponentu.
+  - Rdzeń pure TS w publicznym API: `clusterLocations`, `countryPreset`, projekcja Mercatora
+    (`project`/`unproject`/`boundsOf`/`haversine`/`metersPerPixel`/`zoomForBounds`),
+    generatory HTML znaczników, formatowanie (`formatDistance`, `formatLatLng`) oraz godziny
+    otwarcia (`isOpenAt`, `isAlwaysOpen`, `nextChange`, `groupWeek`, `weekdayName`, `emptyWeek`,
+    `parseTime`, `formatTime`). Testy: `packages/angular/map/src/core/*.test.ts`.
+    `isOpenAt()` liczy dwa dni — bieżący i poprzedni — więc przedział `22:00–01:00` obejmuje
+    wczesne godziny dnia następnego; `24:00` to koniec doby, a nie przejście przez północ.
+    `groupWeek()` skleja sąsiadujące dni o identycznym rozkładzie w `pon.–pt.`, ale nie zawija
+    tygodnia przez granicę niedziela–poniedziałek. Nazwy dni idą z `Intl`, nie ze słownika —
+    karta i edytor godzin działają dla dowolnego locale bez dopisywania tłumaczeń.
+  - Nowe tokeny komponentowe `--kpt-map-*` (w tym `popup-width`, `popup-width-card`,
+    `popup-max-height`, `poi-media-radius`, `poi-row-hover`) oraz klucze i18n `map.*`,
+    `map.poi.*` i `map.field.*` (EN + PL).
+  - Cztery ikony dopisane do **wbudowanego** zestawu `KPT_ICONS`: `mail`, `share`,
+    `external-link`, `crosshair`. Karta miejsca ich potrzebuje, a komponent biblioteczny nie może
+    wymagać `provideKptTablerIcons()`.
+  - `KptInput` przyjmuje `type="time"`.
+  - `KptDatepicker` dostaje wejście `ariaLabel` (nazwa dostępna tam, gdzie pola nie opisuje
+    `<label for>` — np. dwie godziny w jednym wierszu) i w trybie `time` rysuje w polu ikonę
+    zegara zamiast kalendarza. Godziny otwarcia wybiera się właśnie nim
+    (`selectionMode="time"`, `minuteStep=5`), a nie natywnym `<input type="time">`: tamten
+    otwiera systemowy dropdown, którego nie da się ostylować.
+  - **Naprawiony kolor ikony kategorii `muted` poza mapą.** Legenda malowała glif zaszytą
+    bielą na tle koloru roli, a `--kpt-color-muted` to neutral-100 — token tła, nie treści.
+    Kategoria `muted` miała więc w legendzie ikonę praktycznie niewidoczną, choć jej znacznik
+    na mapie był poprawny (ten bierze `contrastVarOf()`). Legenda używa teraz `contrastVarOf()`,
+    a nowe `foregroundVarOf()` w publicznym API daje kolor glifu stojącego wprost na powierzchni
+    (bez własnego tła) — z niego korzysta wiersz kategorii w karcie miejsca.
+  - `renderKptIconSvg()` wydzielone z `kpt-icon` do publicznego API — mapa buduje z niego
+    znaczniki poza Angularem, więc oba miejsca mają jedno źródło prawdy.
+
+  **Nowa zależność opcjonalna:** `leaflet` jako `peerDependencies` + `peerDependenciesMeta.optional`.
+  To pierwsza zależność runtime biblioteki. Ładowana dynamicznym `import()`, więc aplikacje bez mapy
+  jej nie pobierają. Użycie mapy wymaga `pnpm add leaflet` i dołączenia `leaflet/dist/leaflet.css`
+  (Angular CLI: `angular.json → styles[]`, nie `import` w `main.ts`).
+
+  **Uwaga o kaskadzie:** nadpisania `.leaflet-*` w `map.component.scss` stoją poza `@layer` — celowo
+  i jako jedyne w bibliotece. `leaflet.css` nie jest warstwowany, a CSS spoza warstw wygrywa z każdą
+  regułą w `@layer` niezależnie od specyficzności.
+
+  - Podpowiadanie adresu w formularzu „dodaj lokalizację": pole z `autofill` (`city`, `address`,
+    `street`, `houseNumber`, `postcode`, `state`, `county`, `country`, `countryCode`, `label`)
+    wypełnia się z geokodowania wstecznego współrzędnych kliknięcia. Źródło przez port DI
+    `KPT_MAP_GEOCODER`; gotowy adapter `provideKptNominatimGeocoder()` jest **opt-in** —
+    biblioteka nie odpytuje cudzego serwera bez zgody aplikacji. Podpowiedź wypełnia wyłącznie
+    pola puste, więc nigdy nie kasuje tego, co użytkownik wpisał.
+
+  **Uwaga o kaflach:** domyślne `tile.openstreetmap.org` to usługa best-effort bez SLA, z wymogiem
+  widocznej atrybucji i zakazem pre-fetchowania. Do produkcji podstaw własny serwer przez `[tileUrl]`.
+  To samo dotyczy Nominatim (jedno zapytanie na sekundę, zakaz masowego odpytywania) — adapter sam
+  trzyma odstęp, ale produkcja powinna mieć własną instancję albo dostawcę komercyjnego.
+
+  ***
+
+  Przy okazji naprawiony **utajony błąd `KptDialog`**: kontrolki na CDK Overlay (`kpt-select`,
+  `kpt-datepicker`, `kpt-autocomplete`, `kpt-menu`) otwierały się w środku okna modalnego
+  niewidoczne. `showModal()` wynosi `<dialog>` do warstwy szczytowej przeglądarki, ponad całe
+  drzewo dokumentu, a kontener CDK Overlay wisi na `<body>` — żaden `z-index` tego nie przebija.
+  `kpt-dialog` przenosi teraz kontener overlayów do wnętrza okna na czas jego otwarcia i oddaje
+  go na miejsce przy zamknięciu.
+
+  Błąd był w bibliotece od początku, ale nieuruchomiony: żaden przykład nie umieszczał kontrolki
+  overlayowej w oknie modalnym. Ujawnił go formularz „dodaj lokalizację" z pól `date` i `select`.
+
+  **Nieruchomy nagłówek okna.** `.kpt-dialog` jest teraz kolumną flex: nagłówek z krzyżykiem
+  i stopka `[kptDialogFooter]` stoją, a pasek przewijania biegnie wyłącznie wzdłuż
+  `.kpt-dialog__body`. Wcześniej okno przewijało się w całości, razem z nagłówkiem. Treść
+  dostaje `flex: 0 1 auto` + `min-height: 0`, celowo nie `flex: 1` — krótkie okno (`kpt-confirm`)
+  dalej kurczy się do treści, zamiast rozciągać na `max-height`. `display: flex` jest scopowane
+  `&[open]`: regułę `dialog:not([open]) { display: none }` daje arkusz przeglądarki, a każda
+  deklaracja autorska ją bije — także z `@layer`, więc bez scopingu zamknięte okna zostałyby
+  widoczne. `overflow: hidden` na oknie celowo nie ma: przycięłoby panele CDK Overlay
+  przeniesione do jego wnętrza.
+
+  `.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 popup, kontrolki
+  zoomu i menu prawego przycisku są malowane pod kaflami.
+
+  ***
+
+  Naprawiony też **utajony błąd `KptSwitch`, `KptCheckbox` i `KptRadioGroup`**: ukryty `<input>`
+  tych kontrolek jest `position: absolute`, ale ich element główny nie był pozycjonowany. Blokiem
+  zawierającym stawał się więc najbliższy pozycjonowany przodek — w praktyce kontener aplikacji —
+  przez co input uciekał poza przewijany obszar i rozpychał dokument, dając **drugi pasek
+  przewijania** obok paska treści. Kontrolki zatrzymują teraz swój input u siebie
+  (`position: relative` na elemencie głównym).
+
+  Widoczne dopiero, gdy któraś z tych kontrolek trafi dostatecznie nisko w długiej, przewijanej
+  stronie — stąd ujawniło się na stronie mapy, która ma pięć przełączników.
+
+- Geokoder per mapa — nowe wejście `[geocoder]` w `kpt-map`, symetryczne do `[engine]`.
+
+  - `[geocoder]` przyjmuje `KptMapGeocoderPort` i wygrywa nad `KPT_MAP_GEOCODER` z DI. Trafia do
+    obu konsumentów portu naraz: wyszukiwarki adresów i podpowiadania adresu w formularzu
+    „dodaj lokalizację". To samo wejście mają `kpt-map-search` i `kpt-map-create-dialog`, gdy stoją
+    poza mapą. Bez niego nic się nie zmienia — port przychodzi z DI, jak dotąd.
+  - **Po co.** Service Specific Terms §6.2 i §14.2 wiążą geokoder Google z **mapą** Google, a nie
+    z aplikacją. Odkąd `[engine]` pozwala postawić dwa silniki na jednej stronie, globalny provider
+    nie umiał tej reguły dotrzymać: musiałby złamać ją po jednej ze stron. Teraz mapa Leafleta
+    z geokoderem OSM i mapa Google z geokoderem Google mieszczą się obok siebie.
+  - W odróżnieniu od `[engine]` port czytany jest **reaktywnie**: podmiana zeruje listę podpowiedzi
+    i od następnej frazy pyta nowego dostawcę.
+  - `loadGoogleMapsApi(options)` wyeksportowany z `@konce-pt/angular/map` (plus typy
+    `KptGoogleLoadOptions` i `KptGoogleMapsApi`) — ten sam loader, którego używa silnik. Adapter
+    geokodera Google **musi** iść przez SDK, a nie przez REST: web service
+    `maps.googleapis.com/maps/api/geocode/json` odrzuca klucze ograniczone po `Referer`
+    („API keys with referer restrictions cannot be used with this API"), a to jedyna restrykcja
+    mająca sens dla klucza leżącego jawnie w bundlu przeglądarki. CORS na tym endpoincie działa,
+    więc odmowa przychodzi jako `200` z `REQUEST_DENIED` w treści — łatwo ją przeoczyć.
+    Samego adaptera biblioteka nadal nie dostarcza; przykład od początku do końca stoi
+    w playgroundzie.
+
+- Drugi silnik mapy — Google Maps — i wybór silnika per instancja przez wejście `[engine]`.
+
+  - `provideKptGoogleMap({ apiKey, mapId, language?, region?, version?, minZoom?, maxZoom?,
+scrollWheelZoom? })` obok `provideKptLeafletMap()`. **Zero nowych zależności npm**: Google Maps
+    JavaScript API dogrywa się skryptem przy pierwszej mapie, tak jak Leaflet ładuje się dynamicznym
+    `import()`. Paczka `@googlemaps/js-api-loader` dokładałaby wersję do pilnowania w zamian za te
+    same kilkanaście linijek.
+  - **`mapId` jest wymagany.** Bez niego nie działa `AdvancedMarkerElement`, a znaczniki tej
+    biblioteki to gotowy HTML z `marker-html.ts` — starsze `Marker` go nie przyjmie.
+  - Nowe wejście **`[engine]`** (`KptMapEngineFactory | null`) wygrywa nad `KPT_MAP_ENGINE` z DI.
+    Dwie mapy o różnych silnikach mieszczą się dzięki temu na jednej stronie bez komponentów-opakowań.
+    `KPT_MAP_ENGINE` staje się wstrzykiwany opcjonalnie, a brak silnika w obu źródłach daje czytelny
+    komunikat z instrukcją zamiast `NullInjectorError` z nazwą tokenu.
+  - Kontrakt `KptMapEngine` **nie zmienił się o ani jedną sygnaturę** — to był cel tego interfejsu
+    i teraz się zweryfikował. Grupowanie, popup, legenda, menu prawego przycisku, wyszukiwarka
+    i formularz dodawania działają w obu silnikach z tego samego kodu.
+  - Adapter Google liczy `project()`/`unproject()` **rdzeniem** (`core/geo.ts`), a nie
+    `map.getProjection()`: ten zwraca `null` do pierwszego `idle` i tak czy owak wymaga przeliczenia
+    na piksele kontenera. Wspólna matematyka znaczy, że popup ląduje piksel w piksel tak samo w obu
+    silnikach, zgadza się z grupowaniem i obsługuje zoom ułamkowy, którego Google używa przy gestach.
+  - Kliknięcie w znacznik łapie listener DOM ze `stopPropagation()`, a nie `gmp-click`
+    z `gmpClickable`. Bez zatrzymania propagacji to samo kliknięcie doszłoby do mapy i `onMapClick()`
+    zamknąłby popup w tej samej klatce, w której go otwieramy. Adapter Leafleta robi dokładnie to
+    samo przez `L.DomEvent.stopPropagation`; przy okazji odpada zależność od zachowania `gmp-click`
+    w danej wersji API.
+  - Krąg dokładności przy silniku Google jest elementem z tłem, a nie `google.maps.Circle`: Circle
+    przyjmuje kolory w opcjach, a kontrakt repo wymaga stylowania tokenami `var(--kpt-*)`. Średnicę
+    liczy `metersPerPixel()` z rdzenia i odświeża na `zoom_changed`. Silnik trafia na host jako
+    `[data-engine]`, więc różnicę widać w jednej regule SCSS.
+  - `[tileUrl]` i `[attribution]` są przy silniku Google **ignorowane** — kafle i atrybucję dostarcza
+    Google, a jej zasłonięcie albo usunięcie łamie warunki usługi. `setTileSource()` i
+    `invalidateSize()` to tam świadome no-opy.
+
+  **Dlaczego to w ogóle powstało.** 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".
+  Dopóki `kpt-map` umiał tylko Leaflet z kaflami OSM, każdy adapter Google pod `KPT_MAP_GEOCODER`
+  był niezgodny z umową. Silnik Google zdejmuje to u źródła. Sama biblioteka adaptera geokodera
+  Google **nie dostarcza** — jego miejsce jest w aplikacji, bo wolno go użyć tylko z jednym
+  z dwóch silników.
+
+- Wyszukiwarka adresów w `kpt-map` — `[search]` (domyślnie wyłączona) pokazuje w rogu mapy pole
+  z podpowiedziami; wybór podpowiedzi przenosi widok na znalezione miejsce.
+
+  - Port `KPT_MAP_GEOCODER` dostaje **opcjonalną** metodę `search(query, options)` obok istniejącego
+    `reverse()`. Opcjonalną celowo: porty napisane w aplikacjach przed jej powstaniem kompilują się
+    bez zmian, a `kpt-map` bez niej po prostu nie renderuje pola. Nowe typy `KptMapSuggestion`
+    (`{ id, label, at?, bounds?, address? }`), `KptMapSearchResult` (to samo z wymaganym `at`)
+    i `KptMapSearchOptions` w publicznym API; `address` to ten sam `KptMapAddress`, co przy
+    geokodowaniu wstecznym — bez drugiego modelu adresu.
+  - `KptNominatimGeocoder` implementuje `search()` na `/search` i wchodzi w **tę samą kolejkę**
+    co `reverse()`: polityka Nominatim liczy jedno zapytanie na sekundę na całego klienta,
+    a nie na metodę.
+  - **Kolejka adaptera Nominatim liczy odstęp od zegara**, a nie stałym `delay(1000)` przed każdym
+    zapytaniem. Wcześniej pierwsze zapytanie po dowolnie długiej bezczynności też płaciło sekundę
+    — przy podpowiadaniu w trakcie pisania to różnica między „działa" a „zacina się". Zmiana
+    dotyczy także istniejącego `reverse()`; górna granica jednego zapytania na sekundę
+    zostaje nienaruszona.
+  - Nowe w rdzeniu (pure TS, publiczne API): `isFittableBounds(bounds, minSpan?)` i `KPT_MIN_FIT_SPAN`
+    (0,001°, ~100 m) — czy prostokąt warto wpasowywać w kadr, czy potraktować jak punkt.
+    Geokodery obrysowują pojedynczy adres prostokątem rzędu 0,0001°, więc `fitBounds` wjeżdżałby
+    na nim na górny limit zoomu, a dwa sąsiednie adresy lądowałyby w różnych przybliżeniach.
+    Próg wystarczy przekroczyć w jednej osi — długa, wąska ulica dalej zasługuje na `fitBounds`.
+    Testy: `packages/angular/map/src/core/geo.test.ts`.
+  - Nowe wejścia `kpt-map`: `search`, `searchPlaceholder`, `searchOptions`
+    (`minLength` = 3, `debounce` = 300 ms, `limit` = 5, `countryCodes`), `searchZoom` = 16,
+    `searchMarker` = true. Nowe wyjście `searchSelect`.
+  - Wynik z własnym zasięgiem (miasto, region) wchodzi w kadr przez `fitBounds`, a pojedynczy
+    punkt dostaje `[searchZoom]` — dzięki temu każdy adres ląduje w tym samym, przewidywalnym
+    przybliżeniu, niezależnie od tego, jak dostawca obrysował budynek.
+  - Zapytania są nachylone ku presetowi `[country]` (albo `[bounds]`) przez `viewbox`. To sam
+    bias — przestawia kolejność wyników i niczego nie odcina; adres z zagranicy dalej da się
+    znaleźć. Twarde `countrycodes` dokłada się dopiero przy `restrictToCountry` (mapa i tak nie
+    pozwoli przesunąć widoku poza kraj) albo jawnie przez `searchOptions.countryCodes`.
+  - Tymczasowa pinezka wyniku idzie tą samą drogą co reszta znaczników — przez
+    `engine.setMarkers()` — więc przesuwa się z mapą klatka po klatce i **nie wymaga niczego
+    od silnika**. Nie należy do wyniku grupowania, więc kliknięcie w nią nic nie otwiera.
+    Znika po wyczyszczeniu pola i po kliknięciu w mapę.
+  - Nowy komponent `KptMapSearch` (kpt-map-search) w publicznym API — jak legenda, do postawienia
+    także poza mapą. Świadomie **nie** stoi na `kpt-autocomplete`: tamten filtruje opcje po stronie
+    klienta (`includes(q)`), więc wynik geokodera tolerancyjny na literówki wypadałby z listy;
+    jego wartością jest sam `string`, więc nie ma czym przewieźć współrzędnych; i wymaga CDK
+    Overlay, którego mapa poza tym nie potrzebuje. Panel podpowiedzi rysuje więc warstwa Angulara
+    nad mapą, tak samo jak popup i menu prawego przycisku (`z-index: 5`, nad tamtymi).
+  - Wzorzec combobox z `aria-activedescendant` (fokus zostaje w `<input>`), klawiatura ↑/↓/Enter,
+    pierwszy Esc zamyka listę, drugi czyści pole; liczba wyników i „brak wyników" w `aria-live`.
+  - **Port przyjmuje dostawców, którzy nie podają współrzędnych na liście.** `search()` zwraca teraz
+    `KptMapSuggestion` (`at` opcjonalne) zamiast `KptMapSearchResult`, a port może dopisać
+    `resolve(suggestion)`, które dokłada `lat`/`lng` **po wybraniu pozycji**. Tak działa Google Places
+    Autocomplete: oddaje `placeId` i tekst, a współrzędne dociąga osobny Place Details — na tym stoi
+    jego rozliczanie sesyjne, więc bez tego kroku podpowiadanie z Google kosztowałoby pięć wywołań
+    Place Details na każdy zestaw podpowiedzi zamiast jednego na wybór.
+    Zmiana jest **wstecznie zgodna**: `KptMapSearchResult` to teraz `KptMapSuggestion` z wymaganym
+    `at`, więc adaptery zwracające pełne wyniki (Nominatim, Photon, każdy geokoder pytany wprost)
+    spełniają interfejs bez zmiany linijki, a `selected`/`searchSelect` dalej mają ten sam typ.
+  - Obsługa `resolve()` siedzi w `KptMapSearch`, nie w `kpt-map` — dzięki temu **`selected`
+    i `searchSelect` zawsze niosą współrzędne**, także gdy pole stoi poza mapą, i aplikacja nigdy
+    nie musi sprawdzać, czy `at` jest. Podpowiedź ze współrzędnymi emituje się natychmiast (zero
+    opóźnienia dla Nominatima); bez nich panel pokazuje „Szukam…" i `aria-busy`, a nieudane
+    dociągnięcie zostawia etykietę w polu i wraca do listy zamiast wywracać pole. 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.
+  - **`KptNominatimOptions.minIntervalMs`** — sekundowy odstęp przestał być stałą w kodzie.
+    Domyślna zależy od `baseUrl`: publiczna instancja OSM dostaje 1000 ms jak dotąd, własna 0,
+    bo regulamin OSMF nie obowiązuje na cudzym serwerze. `0` zdejmuje też kolejkowanie.
+    Wcześniej własna instancja Nominatima płaciła sekundę za każdą podpowiedź bez żadnego powodu
+    i nie dało się tego wyłączyć opcją.
+  - `provideKptMapGeocoderStub(address, results?, options?)` przyjmuje teraz listę podpowiedzi —
+    Storybook i testy dostają wyszukiwarkę bez ruchu sieciowego. Trzeci argument
+    (`{ deferCoordinates: true }`) każe atrapie udawać dostawcę bez współrzędnych na liście, żeby
+    ścieżkę `resolve()` dało się pokazać bez prawdziwego klucza API. Sygnatura wstecznie zgodna.
+  - Nowe tokeny `--kpt-map-search-width` i `--kpt-map-search-panel-max-height` oraz klucze
+    i18n `map.search.*` (EN + PL).
+  - Wyszukiwarkę pozycjonuje **opakowanie** `<div class="kpt-map__search">`, a nie klasa
+    postawiona wprost na `<kpt-map-search>`. Jeden element z obiema klasami znaczył dwie reguły
+    o identycznej specyficzności (0,1,0) w tej samej warstwie `kpt.components`, więc rozstrzygała
+    kolejność wstrzyknięcia stylów — a Angular wstrzykuje style dziecka po stylach rodzica.
+    `.kpt-map-search { position: relative }` (blok zawierający dla panelu podpowiedzi) wygrywało
+    z `absolute` rodzica, pole wypadało do normalnego przepływu za `.kpt-map__canvas`
+    (`height: 100%`) i znikało przycięte przez `overflow: hidden` widoku. Element był w DOM
+    z poprawnymi atrybutami — usterkę widać wyłącznie na zrzucie ekranu.
+
+  **Uwaga o polityce Nominatim.** Podpowiadanie w trakcie pisania z natury generuje serie zapytań,
+  więc pole broni się progiem `minLength` i `debounce`, a adapter wspólną kolejką i przerywaniem
+  porzuconych zapytań przez `AbortController`. Do produkcji dalej obowiązuje własna instancja
+  (`baseUrl`) albo dostawca komercyjny pod `KPT_MAP_GEOCODER` — publiczna instancja OSM zabrania
+  masowego odpytywania i może zablokować ruch bez uprzedzenia.
+
 ## 0.7.0
 
 ### Minor Changes
@@ -62,7 +442,7 @@
 
 ### Minor Changes
 
-- eecb506: Pierwsze wydanie Koncept UI: design tokeny (OKLCH, motyw jasny/ciemny), bazowy CSS,
+- Pierwsze wydanie Koncept UI: design tokeny (OKLCH, motyw jasny/ciemny), bazowy CSS,
   oraz komponenty Angular 22 — layout (app-shell/toolbar/sidenav/card/divider), formularze
   na Signal Forms (input/select/checkbox/radio/switch/datepicker/form-field), flagowa tabela
   danych (kpt-data-table) z paginatorem, oraz feedback (alert/dialog/toast/tooltip).