@konce-pt/angular 0.6.1 → 0.7.5

package/CHANGELOG.md

@@ -0,0 +1,384 @@
+# @konce-pt/angular
+
+## 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
+
+- Nowy komponent `KptRoadmap` (`kpt-roadmap`) w subpathu `@konce-pt/angular/roadmap` — zadania na
+  poziomej osi czasu w widoku typu Gantt. Przyklejona kolumna etykiet i nagłówek osi, przewijanie
+  w obu osiach, opcjonalna stała wysokość. Zoom: rok / kwartał / miesiąc / tydzień / dzień / godzina,
+  z oknem godzin roboczych. Numeracja tygodni wg ISO 8601 wraz z realnym zakresem dat; zmiana roku
+  oznaczona mocniejszą linią i czarnym znacznikiem. Kolumny zachowują równą szerokość mimo zmiany
+  czasu i różnej długości miesięcy. Grupy zwijane z paskiem zbiorczym, kamienie milowe, zależności
+  FS/SS/FF/SF z wykrywaniem naruszeń, wirtualizacja wierszy. Rdzeń obliczeń jako pure TS — subpath
+  eksportuje `buildTimeline`, `buildRows`, `resolveLinks`, `autoRange` i pomocniki kalendarza ISO.
+  Nowe klucze i18n `roadmap.*` (EN + PL).
+- `KptTooltip`: nowe wejście `kptTooltipOnlyWhenTruncated` — dymek pojawia się wyłącznie wtedy, gdy
+  treść nie mieści się w elemencie i jest ucięta wielokropkiem. Przepełnienie sprawdzane jest przy
+  najechaniu (nie przy renderze), więc wynik pozostaje aktualny po zmianie szerokości czy powiększenia
+  bez użycia `ResizeObserver`. Pomiar obejmuje hosta i jego bezpośrednie dzieci, bo `text-overflow`
+  zwykle siedzi na wewnętrznym elemencie.
+- `KptTooltip`: dymek podąża za hostem przy przewijaniu zagnieżdżonych kontenerów — wcześniej
+  zostawał w miejscu, gdy host przesuwał się we własnym obszarze przewijania.
+
+## 0.6.1
+
+### Patch Changes
+
+- Wydanie porządkowe — wyrównanie wersji paczek. Bez zmian w API.
+
+## 0.6.0
+
+### Minor Changes
+
+- Nowy entry point `@konce-pt/angular/grid` z dyrektywami `[kptGrid]`, `[kptCol]` i `[kptFlex]`
+  (sygnałowe inputy, zoneless) oraz skrótem `KPT_GRID_IMPORTS`. Ustawiają custom properties
+  inline, więc zmiana rozpiętości nie dodaje ani nie usuwa klas w DOM. Wymaga arkusza
+  `@konce-pt/grid`.
+- `llms.txt` podpaczek `charts` i `grid` trafiają teraz do `dist` (wcześniej pomijane).
+
+### Patch Changes
+
+- Updated dependencies
+  - @konce-pt/tokens@0.6.0
+
+## 0.1.2
+
+### Patch Changes
+
+- Naprawa dokumentacji ładowania stylów: metodą główną dla Angular CLI jest `angular.json → styles[]`
+  (import '...css' w main.ts zostaje jako wariant dla Vite/webpack). Tokeny SCSS dostają mixiny
+  `kpt-root-tokens`/`kpt-dark-tokens` emitujące custom properties w runtime. Wejścia CSS dostają
+  warunek `types` + stub `.d.ts` (usuwa TS2882 w projektach z tsc). Bez zmian w API komponentów.
+
+## 0.1.1
+
+### Patch Changes
+
+- Dodano profesjonalne README (EN/PL) i plik LICENSE do każdej paczki oraz metadane npm
+  (repository/homepage/bugs/keywords). Bez zmian w API komponentów.
+
+## 0.1.0
+
+### Minor Changes
+
+- 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).

package/README.md

@@ -93,40 +93,59 @@ import '@angular/cdk/overlay-prebuilt.css';
 
 ## Quick start
 
-A form powered by **Signal Forms** — no `ControlValueAccessor`, no `FormsModule`:
+A login form powered by **Signal Forms** — no `ControlValueAccessor`, no `FormsModule`:
 
 ```ts
-import { Component, signal } from '@angular/core';
-import { form, required, email, FormField } from '@angular/forms/signals';
-import { KptFormField, KptInput, KptSelect, KptButton } from '@konce-pt/angular';
+import { Component, computed, signal } from '@angular/core';
+import { FormField, FormRoot, email, form, required, submit } from '@angular/forms/signals';
+import { KptButton, KptFormField, KptInput } from '@konce-pt/angular';
 
 @Component({
   selector: 'app-login',
-  imports: [FormField, KptFormField, KptInput, KptSelect, KptButton],
+  imports: [FormRoot, FormField, KptFormField, KptInput, KptButton],
   template: `
-    <kpt-form-field label="E-mail" required>
-      <kpt-input [formField]="loginForm.email" type="email" placeholder="you@company.com" />
-    </kpt-form-field>
-
-    <kpt-form-field label="Role">
-      <kpt-select [formField]="loginForm.role" [options]="roles" placeholder="Pick a role…" />
-    </kpt-form-field>
-
-    <kpt-button (click)="submit()">Sign in</kpt-button>
+    <!-- formRoot sets novalidate, intercepts submit and calls submit() for you -->
+    <form [formRoot]="loginForm" (submit)="onSubmit()">
+      <kpt-form-field label="E-mail" [error]="emailError()" required controlId="f-email">
+        <kpt-input [formField]="loginForm.email" type="email" id="f-email" />
+      </kpt-form-field>
+
+      <kpt-form-field label="Password" [error]="passwordError()" required controlId="f-pass">
+        <kpt-input [formField]="loginForm.password" type="password" id="f-pass" />
+      </kpt-form-field>
+
+      <kpt-button type="submit" [disabled]="formInvalid()">Sign in</kpt-button>
+    </form>
   `,
 })
 export class Login {
-  readonly model = signal({ email: '', role: null as string | null });
+  readonly model = signal({ email: '', password: '' });
   readonly loginForm = form(this.model, (p) => {
-    required(p.email); email(p.email);
-    required(p.role);
+    required(p.email, { message: 'E-mail is required' });
+    email(p.email, { message: 'Enter a valid e-mail address' });
+    required(p.password, { message: 'Password is required' });
   });
-  readonly roles = [{ label: 'Admin', value: 'admin' }, { label: 'Editor', value: 'editor' }];
 
-  submit() { if (this.loginForm().valid()) console.log(this.model()); }
+  // Validators stay pure — only the *message* waits for the field to be touched.
+  private errorFor(name: 'email' | 'password'): string | null {
+    const s = this.loginForm[name]();
+    return s.touched() && s.invalid() ? s.errors()[0]?.message ?? null : null;
+  }
+  readonly emailError = computed(() => this.errorFor('email'));
+  readonly passwordError = computed(() => this.errorFor('password'));
+  readonly formInvalid = computed(() => this.loginForm().invalid());
+
+  async onSubmit(): Promise<void> {
+    // submit() marks the whole tree as touched before running the action
+    await submit(this.loginForm, { action: async () => { console.log(this.model()); } });
+  }
 }
 ```
 
+> Don't gate validators on UI state (`when: ({ state }) => state.touched()`) — it makes
+> `loginForm().valid()` return `true` on an untouched form. Koncept UI controls already show
+> the invalid state only once a field is touched.
+
 Data table with sorting, filtering, pagination and a custom cell template:
 
 ```html