@konce-pt/angular 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -1,5 +1,385 @@
 # @konce-pt/angular
 
+## 0.8.5
+
+### Minor Changes
+
+- f615e93: Nowe wejście `adaptive` w `KptBackdrop`: barwy wpisane na sztywno przenoszą się na powierzchnię
+  bieżącego motywu.
+
+  Literał z założenia stoi w miejscu i tak ma być — `#5b8af2` to barwa marki, a nie sugestia.
+  Ale sekcja z `color="#000000"` na `background="#ffffff"` w motywie ciemnym zostawała białą kartą
+  wyciętą w ciemnej stronie, razem z treścią dobraną do tamtego tła. Do tej pory jedynym wyjściem
+  było przepisanie wejść na tokeny; teraz wystarczy `[adaptive]="true"`.
+
+  Adaptacja przenosi `color`, `colors` i `background` na powierzchnię bieżącego motywu, zachowując
+  odległość każdej barwy od tej powierzchni: czerń dobrana do bieli wychodzi bielą na tle
+  `neutral-950`, a białe tło wychodzi w jasności samej powierzchni. Rusza wyłącznie jasność — `a`
+  i `b` w OKLab zostają nietknięte, więc odcień i nasycenie przeżywają i barwa marki nie zmienia się
+  w inną barwę, tylko dobiera jasność do tła. Jasność wypychająca wynik poza sRGB zostaje przycięta
+  w drodze powrotnej, co kosztuje około trzech stopni odcienia i dziesiątą część nasycenia; za tłem
+  sekcji to niewidoczne, a własne mapowanie gamutu byłoby kosztem bez pokrycia.
+
+  Rusza wyłącznie literały. Puste wejście bierze token, a zapis przez `var()` też sięga po token —
+  jedno i drugie już idzie za motywem i adaptacja odwróciłaby je drugi raz, czyli z powrotem.
+  Punktem odniesienia jest motyw jasny, bo biblioteka trzyma jasny w `:root`, a ciemny jako
+  nadpisanie; to jedyne założenie, jakie ta zamiana robi.
+
+  W rdzeniu doszły `adaptLightness()` i `adaptToSurface()` — czysta arytmetyka z testami
+  `node --test` — oraz `readBackdropSurface()` i `adaptBackdropValue()` spinające je z drzewem.
+  Strażnik przebudowy liczy teraz kolor wiodący tą samą drogą co budowa; inaczej porównywałby
+  wartość sprzed adaptacji z zapamiętaną po adaptacji i przebudowywał renderer bez końca.
+
+- f615e93: Sekcja z własnym tłem dobiera kolor treści do tego tła i ogłasza ton atrybutem `data-tone`.
+
+  Host malował `--kpt-color-surface` i zostawiał treści `--kpt-color-on-surface`. To jest słuszne,
+  dopóki sekcja nie dostanie własnego `background` — wtedy ten token opisuje stronę dookoła, a nie
+  to, na czym treść naprawdę leży. Sekcja z ciemnym tłem w motywie jasnym miała `color` prawie czarny
+  na prawie czarnym tle, czyli treść niewidoczną. Każdy konsument musiał to obchodzić sam; demo
+  playgroundu obchodziło, licząc jasność tła po swojej stronie, więc błąd nie był widoczny akurat
+  tam, gdzie się go szuka.
+
+  Teraz komponent liczy to sam: `color` na hoście idzie pod tło, które sekcja naprawdę maluje,
+  a wynik wychodzi na zewnątrz jako `data-tone` (`light` przy jasnym tle, `dark` przy ciemnym).
+  Napis bierze kolor dziedziczeniem, a to, czemu sam kolor tekstu nie wystarcza — przyciski i inne
+  komponenty w sekcji — podwiesza własne tokeny pod atrybut:
+
+      :where(kpt-backdrop[data-tone='light']) .hero { --kpt-button-filled-bg: #15181a; }
+
+  Ton liczy się po adaptacji, więc pod `adaptive` zgadza się z tłem malowanym, a nie z wpisanym
+  w szablonie. Sekcja bez własnego `background` nie ogłasza nic i treść zostaje na
+  `--kpt-color-on-surface` — dla niej nic się nie zmienia.
+
+  O kontraście rozstrzyga jasność względna WCAG (`relativeLuminance`, `prefersDarkContent`
+  w rdzeniu, z testami), a nie jasność OKLab: pierwsza mówi, ile z barwy wychodzi światła, druga jak
+  jasno barwa wygląda, i tylko na pierwszej stoi rachunek kontrastu.
+
+  Playground dostał przełącznik „Idź za motywem" dla `adaptive` i przestał liczyć jasność tła po
+  swojej stronie — podpina się pod `data-tone` komponentu, więc jedna polityka zamiast dwóch.
+
+- f615e93: Rampa `colors` w `KptBackdrop` przyjmuje dowolny zapis CSS, nie tylko heksadecymalny.
+
+  Wstęga miesza barwy po biegunowej postaci OKLab, ale dostawały się tam dotąd wyłącznie przystanki
+  sparsowane przez `parseHexColor` — czyli `#rgb` i `#rrggbb`. `oklch()`, `color-mix()`, `rgb()`,
+  nazwy własne i `var(--kpt-*)` wypadały z rampy, a gdy wypadły wszystkie, renderer schodził do
+  `IDLE` i **kadr zostawał pusty bez żadnego sygnału**. Tym dotkliwiej, że rampa domyślna — ta,
+  której się nie podaje — od początku szła przez `readCssColor` i rozumiała każdy zapis, bo tokeny
+  biblioteki są zapisane w OKLCH. Podana rampa miała gorszy parser niż niepodana.
+
+  Teraz obie idą tą samą drogą: o znaczenie każdego przystanku pytamy przeglądarkę, a do renderera
+  trafia już sam hex — jego kontrakt się nie zmienia. Przystanek, którego przeglądarka nie przyjmuje,
+  wypada z rampy; gdy wypadną wszystkie, wchodzi rampa wyprowadzona z koloru wiodącego, zamiast gasić
+  sekcję. Najczęstsza pomyłka, `var(--kpt-color-primary)` w rampie, i tak celuje w ten właśnie kolor,
+  więc użytkownik dostaje niemal to, o co mu chodziło, plus jedno ostrzeżenie w konsoli w buildzie
+  dev. Wartość alfa wypada — tablica barw wstęgi jest RGB.
+
+  `readCssColor()` zwraca `null` na wartości, której przeglądarka nie uznaje za kolor. Dotąd dawała
+  czerń, bo `fillStyle` odrzuca taki zapis po cichu i zostaje przy poprzednim — nie dało się odróżnić
+  śmiecia od legalnej czerni ani o czymkolwiek ostrzec. Rozstrzyga to para różnych wartowników: przy
+  wartości nieprawidłowej każdy zostaje na swoim miejscu i oba przebiegi się rozchodzą. Przy okazji
+  sonda jest czyszczona przed każdym odczytem — barwa z kanałem alfa mieszała się z tym, co zostawiło
+  poprzednie wywołanie.
+
+- f615e93: Wejścia koloru `KptBackdrop` rozumieją `var()`, więc barwa podana w szablonie może iść za motywem.
+
+  Kolor wiodący był dotąd brany z wejścia bez zmian, a sonda 1×1 jest oderwana od drzewa — zapis
+  `color="var(--kpt-color-primary)"` nie miał prawa zadziałać i lądował w ostrzeżeniu. Zamrożenie
+  literału jest poprawne (`#5b8af2` ma zostać `#5b8af2`), ale odcinało jedyny zapis, który sam
+  wiedziałby, co zrobić przy przełączeniu motywu: wyrażenie odwołujące się do tokenów.
+
+  Doszedł `resolveCssValue()`: wyrażenie trafia do własności-sondy na elemencie w drzewie, a z jego
+  wyliczonego stylu wraca już z podstawionym `var()`. Dalej idzie do `readCssColor`, bo `color-mix()`
+  zostaje w custom property niewyliczone, a canvas je wylicza. Dzięki temu
+
+      <kpt-backdrop color="color-mix(in oklab, #5b8af2, var(--kpt-color-surface) 30%)">
+
+  daje kwadraciki, które jaśnieją na jasnej powierzchni i ciemnieją na ciemnej, przy jednej wartości
+  w szablonie — przeliczane istniejącym już nasłuchem motywu. To samo działa dla przystanków rampy
+  `colors`. Biblioteka nie zgaduje przy tym, jaki kolor jest „odpowiedni" w drugim motywie: decyduje
+  autor wyrażenia. Zapis bez `var()` omija całą ścieżkę, więc literał nie płaci za nic.
+
+  Sonda musi pisać poza zasięgiem nasłuchu motywu, bo ten ogląda `style` hosta i jego przodków —
+  zapis na hoście budziłby nasłuch, ten sięgałby po kolor na nowo i pętla nie miałaby końca. Stąd
+  `resolveBackdropColors()` i `readBackdropLead()` dostają teraz canvas komponentu, a nie hosta;
+  tokeny czytają się z niego tak samo, bo `--_dot` dziedziczy się w dół.
+
+  Nazwa zmiennej, która nic nie daje, schodzi przy `color` do tokenu — tego chce autor literówki —
+  a przy `colors` wypada z rampy i trafia do istniejącego ostrzeżenia w buildzie dev.
+
+- c1f8885: Nowe animowane tło `KptBackdrop` (`kpt-backdrop`) i pod nim nowa paczka `@konce-pt/backdrop` —
+  rdzeń pure-TS z testami `node --test`. Komponent jest opakowaniem sekcji: canvas leży pod spodem,
+  rzutowana treść warstwę wyżej i zachowuje się zwyczajnie, więc pod hero z nagłówkiem i przyciskami
+  nie trzeba układać niczego ręcznie.
+
+  Efekt `signal-grid` to drobna siatka kwadratów, które cicho migoczą — gęsta przy krawędzi wskazanej
+  przez `anchor`, wygasająca do pustki przy przeciwnej. Gradient bierze się z tego, **ile** kwadratów
+  się pali, a nie z przezroczystości nałożonej na równomierną siatkę: to różnica między czymś, co
+  czyta się jak sygnał, a fakturą z maską na wierzchu. Sterują tym `density` (udział zapalonych
+  komórek przy kotwicy) i `falloff` (jak szybko to gaśnie), a rozstawem `cell` i `gap`.
+
+  Każda komórka wylicza swoje losowania — czy się pali, fazę i tempo migotania — z własnej kolumny
+  i wiersza przez `kptHash01()`. Siatka nie może trzymać stanu między klatkami, bo przy zmianie
+  rozmiaru komórki wędrują i tablica `Math.random()` rozsypałaby cały obraz; przy losowaniu
+  z pozycji układ przeżywa zmianę rozmiaru okna zamiast tasować się od nowa. Tempa są rozstrzelone
+  w przedziale 0,45–1,55, bo przy jednym tempie cała siatka pulsuje zgodnie i zamiast migotania
+  wychodzi oddech. Siatka celowo wychodzi poza obszar, a nadmiar jest ucinany — siatka kończąca się
+  przed krawędzią wygląda na uciętą.
+
+  Rysowanie stoi, gdy nie ma czego oglądać: sekcja poza ekranem (`IntersectionObserver`), karta w tle,
+  ustawione `paused`, `speed` równe zeru albo `prefers-reduced-motion`, o który komponent pyta sam.
+  Zostaje wtedy jedna statyczna klatka ze zróżnicowaną jasnością, nie pustka — efekt jest częścią
+  kompozycji, nie ozdobą. `speed` wchodzi w zegar (`clock += krok * speed`), a nie w fazę, więc suwak
+  prędkości przyspiesza obraz zamiast go przeskakiwać.
+
+  Kolor kwadratów bierze się z `--kpt-color-primary`, tło z `--kpt-color-surface`; oba da się nadpisać
+  wejściami `color` i `background` albo własnościami `--kpt-backdrop-color` i `--kpt-backdrop-surface`,
+  bo sekcja promocyjna bywa w kolorach spoza palety aplikacji. Canvas nie rozwija `var()`, więc token
+  odczytuje się z wyliczonego stylu hosta i na nowo po zmianie motywu. Canvas nosi `aria-hidden="true"`
+  i `pointer-events: none` — to dekoracja bez treści i bez niczego do trafienia.
+
+  Rdzeń (`buildSignalGrid`, `signalGridAlpha`, `signalGridDensity`, `kptHash01`) jest re-eksportowany
+  z `@konce-pt/angular`, więc aplikacja nie instaluje paczki samodzielnie, a ten sam efekt da się
+  narysować własnym rendererem. Port Reacta dostanie komponent osobno.
+
+- c1f8885: Drugi efekt tła — `wave` — i `KptBackdrop` w porcie Reacta.
+
+  `wave` to jedna miękka wstęga światła płynąca przez kadr, z barwami przesuwającymi się wzdłuż niej
+  i bez twardej krawędzi w całym obrazie. Linia środkowa jest sumą harmonicznych o niewspółmiernych
+  częstotliwościach, więc prąd faluje bez powtarzalnego wzoru; jasność opada od niej krzywą Gaussa
+  i to opadanie odróżnia prąd światła od paska. Nowe wejścia: `colors` (rampa barw), `rotation`
+  (kąt, pod jakim prąd przecina kadr — odpowiednik `anchor` z signal-grid, tyle że płynny), `band`
+  i `amplitude`. Wejście nienależące do bieżącego efektu po prostu nie jest czytane.
+
+  Rampa barw jest zamknięta w pętlę i mieszana po **biegunowej** postaci OKLab. Interpolacja sRGB
+  miesza wartości po gammie i wychodzi błotem, a nawet prostokątny OKLab przecina oś achromatyczną
+  dla przeciwnych odcieni: w połowie drogi z niebieskiego w żółty zostaje szarość dokładnie tam,
+  gdzie prąd świeci najmocniej. Odcień idzie krótszym łukiem, a przystanek bez nasycenia przejmuje
+  odcień sąsiada, bo `atan2` na zerowym nasyceniu zwraca kąt przypadkowy. Bez podanego `colors` rampą
+  jest `--kpt-color-primary` i dwie barwy wyprowadzone z niego obrotem odcienia — paleta biblioteki
+  jest neutralna, więc sięganie po tokeny statusowe do celów dekoracyjnych byłoby użyciem semantyki
+  nie na miejscu.
+
+  Wstęga liczy się w buforze o dłuższym boku 160 px i jest skalowana w górę: miękkość bierze się
+  z interpolacji przeglądarki, więc kilka tysięcy pikseli na klatkę obsługuje kadr dowolnej
+  wielkości. Krótszy bok ma osobną podłogę 72 próbek — przy proporcjonalnym skalowaniu szeroki kadr
+  miałby kilkadziesiąt wierszy i prąd obrócony blisko kąta prostego łamałby się właśnie wzdłuż tej
+  osi.
+
+  **Renderery przeniosły się do `@konce-pt/backdrop`.** Rysowanie nie potrzebuje frameworka, tylko
+  `CanvasRenderingContext2D`, więc `createBackdropRenderer()` (plus `resolveBackdropColors()`
+  i stałe cyklu życia) mieszka teraz w rdzeniu, a komponent w obu portach jest samym cyklem życia:
+  rAF, `ResizeObserver`, `IntersectionObserver`, zapytanie o ograniczony ruch i obserwator motywu.
+  Te same wejścia dają dzięki temu tę samą klatkę w Angularze i w Reakcie. Doszedł też
+  `readCssColor()` — tokeny są zapisane w OKLCH, a rampę trzeba wymieszać, nie tylko podać dalej,
+  więc o znaczenie zapisu pytamy przeglądarkę, malując kolor na canvasie 1×1.
+
+  `@konce-pt/react` dostaje `KptBackdrop` z kompletem propsów obu efektów, ten sam DOM i ten sam
+  arkusz `components.css`. Zmianę `colors` śledzi po treści tablicy, nie po jej tożsamości, więc
+  nowa tablica z renderu rodzica nie przebudowuje renderera.
+
+- ce34ab3: Nowa rodzina `KptChat` w subpathu `@konce-pt/angular/chat`: `kpt-chat` (lista rozmowy),
+  `kpt-chat-message` (bąbel), `kpt-chat-typing` (wskaźnik pisania), `kpt-chat-composer` (pole
+  pisania) i `kpt-chat-dock` (pływający panel w rogu, zbudowany na `kpt-fab`). Subpath, nie rdzeń —
+  aplikacje bez czatu nie mają powodu pobierać docka razem z logiką breakpointów.
+
+  Nowa paczka `@konce-pt/chat` — rdzeń pure-TS z testami `node --test`. `buildChatRows()` zamienia
+  płaską listę wiadomości na wiersze do wyrenderowania: separatory dni, dzielnik nieprzeczytanych
+  i pozycję w grupie, z której wynika zapadnięty narożnik, ogonek, awatar i wiersz z godziną.
+  Grupa łamie się na zmianie autora, przerwie powyżej pięciu minut, granicy doby kalendarzowej,
+  wiadomości systemowej i dzielniku nieprzeczytanych. Doba liczona jest od północy do północy,
+  a nie odejmowaniem znaczników czasu — doba ze zmianą czasu ma 23 albo 25 godzin, więc „wczoraj
+  o 23:30" wypadałoby raz do roku o dzień obok.
+
+  Nieudana wysyłka umie o sobie powiedzieć: `status: 'failed'` obwodzi bąbel kolorem
+  `--kpt-color-danger-border` i stawia strzałkę ponowienia **poza** nim, po zewnętrznej stronie
+  listy. Taki bąbel pokazuje wiersz meta nawet w środku grupy — strzałka bez niczego, co ją
+  tłumaczy, byłaby zagadką. Pasek `[offline]` liczy wiadomości czekające na wysłanie przez
+  `pendingCount()`. Potwierdzenia z serwera przychodzą nie po kolei, więc `mergeStatus()` zostawia
+  wyższy stopień: spóźnione „dostarczone" nie cofnie `read`. Wyjątkiem jest `failed`, który wygrywa
+  zawsze — wiadomość odrzucona po wysłaniu nie może zostać na zawsze „wysłana".
+
+  Transport zostaje w aplikacji: komponent przyjmuje wiadomości i tylko zgłasza `(retry)`
+  oraz `(loadMore)`.
+
+  Bąble są rozłożone pod monochromatyczny motyw biblioteki: różnicę robi jasność, nie odcień.
+  Wiadomość przychodząca siada na `--kpt-color-muted`, własna domyślnie na pełnym
+  `--kpt-color-primary`. `--kpt-color-surface-variant` dzieli od tła listy 1,5% jasności, więc bąbel
+  przychodzący na nim po prostu znikał, a `--kpt-color-primary-subtle` ma dokładnie jasność
+  `--kpt-color-muted`, przez co własny i cudzy bąbel były nie do odróżnienia. Wariant `primary`
+  zostaje jako cichsza opcja dla własnych wiadomości; wariant `muted` zniknął, bo po tej zmianie
+  powielał `neutral`. Przyklejona pigułka separatora dnia przejeżdża nad wiadomościami, więc dostała
+  podniesione tło, ramkę i cień — bez nich zlewała się z bąblem, po którym właśnie jechała.
+
+  `kpt-scroll-top` przykleja się dokładnie w to samo miejsce co dock, z tym samym `--kpt-z-overlay`,
+  i połykał FAB czatu w całości — wystawała sama plakietka nieprzeczytanych, a przycisku nie dało się
+  kliknąć. Arkusz rozwiązuje to teraz sam: przy docku `bottom-end` przycisk powrotu na górę ustępuje
+  w bok o szerokość FAB-a. W bok, nie do góry, bo nad FAB-em stoi panel rozmowy — przesunięcie
+  w pionie zamieniłoby jedną kolizję na gorszą. Do tego `kpt-chat-dock` dostaje `offset` na wypadek
+  innych widgetów w tym rogu.
+
+  Słownik `@konce-pt/i18n` dostaje sekcję `chat` (EN i PL). Rdzeń zwraca **rodzaj** etykiety dnia
+  (`{ kind: 'today' }`), a nie napis — brzmienie należy do słownika, nazwa dnia tygodnia do `Intl`,
+  a paczka bez zależności nie ma po co wozić tłumaczeń.
+
+  Port Reacta dostaje subpath `@konce-pt/react/chat` z kompletem pięciu komponentów na tym samym
+  rdzeniu i tym samym arkuszu `components.css` — te same klasy `kpt-*` i te same atrybuty `data-*`,
+  więc oba porty renderują identycznie. `model()` z Angulara rozpada się na pary
+  controlled/uncontrolled (`value`/`defaultValue`/`onValueChange`, `open`/`defaultOpen`/`onOpenChange`),
+  a `<ng-template let-message>` na `renderMessage(message, row)`.
+
+  Zestaw wbudowany `@konce-pt/icons` rośnie z 86 do 92 ikon: `checks`, `paperclip`, `send`,
+  `message-circle`, `corner-up-left`, `mood-smile`. Bez `checks` nie dałoby się odróżnić
+  „dostarczono" od „wysłano", a komponenty biblioteki muszą działać bez `provideKptTablerIcons()`.
+
+- 7626e71: `KptChip` dostaje wejście `textTransform` (`'none' | 'capitalize' | 'uppercase' | 'lowercase'`,
+  domyślnie `'none'`) w obu portach. Ląduje jako `data-text-transform` na `.kpt-chip` i tam ustawia
+  `text-transform`, więc etykieta zostaje w treści zapisana po swojemu, a o sposobie jej wyświetlenia
+  decyduje chip — pigułka nad nagłówkiem hero wygląda tak samo niezależnie od tego, czy tekst
+  przyszedł ze słownika, z CMS-a czy z API.
+
+  `capitalize` podnosi pierwszą literę każdego słowa — **także po dywizie** („Agent-Ready"), bo CSS
+  nie wie, gdzie kończy się wyraz złożony. Przy etykietach z myślnikiem pewniejszy jest zapis wprost
+  w treści; to samo ograniczenie ma każde `text-transform: capitalize`, a nie ta implementacja.
+
+- a1c5468: `KptDataView` dostaje `pageSizeOptions`, a rozmiar strony staje się sterowalny — w Angularze
+  `pageSize` to teraz `model`, w React dochodzą `defaultPageSize` i `onPageSizeChange`. Do tej pory
+  komponent podawał paginatorowi `[pageSize()]` jako jedyną opcję, więc select „Wierszy" był martwą
+  kontrolką: pokazywał liczbę, której nie dało się zmienić. Pager zostaje widoczny także wtedy, gdy
+  wszystko mieści się na jednej stronie, o ile jest w czym wybierać — inaczej wybranie największego
+  rozmiaru chowałoby select, którego użytkownik właśnie użył.
+
+  Pasek paginatora w `KptDataView` znów stoi w jednym rzędzie po prawej. Opakowanie ustawiało
+  `.kpt-data-view .kpt-paginator { display: block }`, a selektor potomka bije `.kpt-paginator
+{ display: flex }` z tej samej warstwy — trzy bloki paginatora rozpadały się na trzy linie.
+
+  `KptDataView` pozwala ustawić gęstość siatki: `gridColumns` (dwukierunkowe), `gridColumnsOptions`
+  i `gridMinWidth`. Przy więcej niż jednej opcji w układzie siatki pasek narzędzi dostaje drugą grupę
+  segmentową z ikoną `grid-dots`. Wybrana liczba jest sufitem, nie sztywną liczbą — minimum ścieżki
+  rośnie do szerokości jednej z N kolumn, więc wąski kontener schodzi niżej, zamiast ściskać karty
+  poniżej `gridMinWidth`. Do tej pory o gęstości decydował wyłącznie arkusz aplikacji, bo komponent
+  miał `minmax(10rem, 1fr)` wpisane na sztywno.
+
+  Przyciski przełącznika układu niosą wreszcie `aria-pressed` — czytnik ekranu nie ogłaszał, który
+  układ jest włączony.
+
+  Przycisk siatki w przełączniku układu rysuje `layout-grid` zamiast `menu`: hamburger to
+  semantycznie lista, nie siatka. `layout-grid` wchodzi do zestawu wbudowanego `KPT_ICONS`
+  (86 ikon, razem z `grid-dots` dla paska gęstości), bo komponent biblioteki musi działać bez `provideKptTablerIcons()`.
+
+- 0daa856: Nowa karta podglądu `KptPeek` (`kpt-peek` + `kptPeekTrigger`) i na niej wzmianki w tekście:
+  `KptMention` (pojedyncza wzmianka) oraz `KptMentions` (akapit rozbity na treść i wzmianki).
+  Obie rzeczy w rdzeniu biblioteki, nie w subpathu — karta jest mała i przyda się wszędzie tam,
+  gdzie tooltip za mało niesie, a popover za dużo zasłania.
+
+  `kptTooltip` ma `pointer-events: none`, więc linku w jego środku nie da się kliknąć, a `kpt-popover`
+  otwiera dopiero klik i kładzie na stronie backdrop. `kpt-peek` stoi pomiędzy: hover otwiera kartę
+  po `openDelay`, zjazd kursora zamyka po `closeDelay` (najazd na kartę anuluje zamknięcie, bo kursor
+  musi mieć czas przejechać z triggera na kartę), a treść karty jest w pełni interaktywna i niczego
+  nie przykrywa. Fokus otwiera bez zwłoki, a klik, Enter albo dotyk **przypina** kartę: zostaje mimo
+  zjazdu kursora, a fokus wchodzi do środka. To jedyna droga do treści karty tam, gdzie hovera nie ma
+  w ogóle, więc interaktywna karta zostaje osiągalna na dotyku i z klawiatury. Escape zamyka i oddaje
+  fokus triggerowi.
+
+  Nowa paczka `@konce-pt/mention` — rdzeń pure-TS z testami `node --test`. `parseMentionText()`
+  rozbija akapit na treść i wzmianki (`@id` albo `@[Nazwa ze spacją](id)`), `mentionQuery()` mówi,
+  czy kursor stoi w zapytaniu `@…`, a `filterMentions()` dopasowuje podpowiedzi. Sklejenie segmentów
+  wraca do oryginału znak w znak — podgląd rozjeżdżający się z zapisaną treścią byłby gorszy niż brak
+  podglądu. `mail@example.com` wzmianką nie jest: `@` musi stać na początku tekstu albo po znaku,
+  który nie jest literą, cyfrą ani podkreśleniem. Dopasowanie zdejmuje diakrytyki, a litery z kreską
+  mapuje ręcznie — `ł` to osobny znak Unicode, nie `l` ze znakiem diakrytycznym, więc samo NFD
+  zostawiłoby „Łukasza" poza zasięgiem zapytania „lukasz".
+
+  W treści zapisuje się **identyfikator**, nie nazwa: `id` przeżyje zmianę nazwiska, a etykieta
+  bierze się z listy pozycji. Identyfikator spoza listy też się renderuje — etykietą zostaje wtedy on
+  sam, bo notatka ma dać się przeczytać także wtedy, gdy ktoś odszedł z zespołu. `kpt-mentions` nie
+  renderuje HTML-a: akapit wchodzi jako zwykły napis, a wzmianka jest elementem, który biblioteka sama
+  zbudowała — aplikacja nie musi przepuszczać przez sanitizer treści pisanej przez użytkowników tylko
+  po to, żeby wyszły z niej wzmianki. Bez szablonu karty wzmianka jest wyróżnionym słowem, a nie
+  przyciskiem: nie ma czego otworzyć, więc niczego nie udaje.
+
+  `kpt-rich-text` dostaje `mentions`, `mentionLimit` i `(mentioned)`: napisanie `@` otwiera listę
+  podpowiedzi zaczepioną w miejscu kursora, strzałki po niej chodzą, Enter albo Tab wstawia, Escape
+  zamyka. Zapytanie czytamy z węzła tekstowego przy kursorze, nie z HTML-a — w treści siedzą tagi,
+  a `@` ma widzieć tylko to, co naprawdę napisano w tym miejscu. Wstawiona wzmianka to
+  `<span class="kpt-mention" data-mention="id" contenteditable="false">` plus twarda spacja:
+  identyfikator przeżywa obieg przez wartość, `contenteditable="false"` trzyma wzmiankę w jednym
+  kawałku (bez tego kursor wchodzi w środek nazwiska), a spacja daje mu gdzie stanąć za blokiem,
+  w który nie da się wejść. Oba atrybuty weszły na allowlistę sanitizera w obu portach — są bierne,
+  nie wykonują niczego i nie wskazują zasobów.
+
+  `KptIconButton` w porcie Angulara dostaje `ariaExpanded` — jak `ariaPressed` musi zjechać na
+  wewnętrzny `<button>`, bo host nie ma roli przycisku. Słownik `@konce-pt/i18n` dostaje
+  `richText.mentions` (EN i PL) na etykietę listy podpowiedzi.
+
+  Port Reacta dostaje komplet: `KptPeek`, `KptMention`, `KptMentions` i te same trzy propsy
+  w `KptRichText`, na tym samym rdzeniu i tym samym arkuszu `components.css`. Propsy wyzwalacza
+  `KptPeek` lądują na samym elemencie podanym w `trigger` (klon z doklejonymi handlerami), więc
+  `aria-expanded` siedzi tam, gdzie czytnik ekranu naprawdę je przeczyta.
+
+- `KptPickList` i `KptOrderList` dostają przeciąganie i dwuklik — w obu portach.
+
+  Nowe wejście `dragdrop` jest domyślnie wyłączone, tak samo jak `reorderable` w tabeli danych:
+  przeciąganie to zachowanie, na które trzeba się zgodzić, a nie takie, które ma się włączyć samo
+  komuś, kto tylko wyświetla listę. Włączone, porządkuje pozycje wewnątrz panelu, a w pick-liście
+  przenosi je także między panelami, na wskazane miejsce. Upuszczenie na pusty obszar listy dopina
+  element na koniec.
+
+  Upuszczony element ląduje **na pozycji tego, na który go upuszczono** — nie zamienia się z nim
+  miejscami. To ten sam wzór co przestawianie kolumn w tabeli; zamiana miejscami wygląda przy
+  dłuższej liście na przypadek, bo element skacze w dwa miejsca naraz.
+
+  Dwuklik w pick-liście przerzuca pojedynczą pozycję na drugą stronę, w obie strony i niezależnie
+  od zaznaczenia. Nie wymaga `dragdrop`, bo dwa kliknięcia pod spodem i tak się znoszą.
+
+  Pod spodem natywny HTML5 drag and drop, nie CDK. Port React ma mieć to samo zachowanie i ten sam
+  arkusz stylów, a dla CDK nie byłoby tam odpowiednika — jedna implementacja zamiast dwóch
+  rozjeżdżających się. Przyciski zostają pełną ścieżką z klawiatury, bo przeciąganie nie ma
+  klawiaturowego odpowiednika i bez nich sortowanie stałoby się niedostępne.
+
+### Patch Changes
+
+- f615e93: `KptBackdrop` idzie za tokenami, a nie za samym atrybutem motywu.
+
+  Canvas nie rozwija `var()`, więc kolor wiodący jest odczytywany raz i zapiekany w rendererze —
+  zmianę tokenów trzeba zauważyć i odczytać je na nowo. Dotąd nasłuch obejmował `data-theme`
+  i `class` na `<html>`, co wystarczało na przełącznik jasny/ciemny i zostawiało trzy dziury:
+  nadpisanie tokenu inline (konfigurator marki ustawia `--kpt-color-primary` na `<html>` — reszta
+  strony się przemalowywała, tło zostawało na starej barwie), motyw zakresowy (`[data-theme="dark"]`
+  nie jest przywiązany do `:root`, więc niesie go dowolny przodek) oraz aplikację trzymającą ciemne
+  tokeny w media query zamiast w atrybucie.
+
+  Nasłuch idzie teraz po łańcuchu od hosta aż do `<html>` i patrzy u każdego przodka na `data-theme`,
+  `class` i `style`, a obok tego na zapytanie `prefers-color-scheme`. Szersza sieć łapie też zmiany
+  niemające nic wspólnego z barwą — klasa nakładki na `<html>` przy otwarciu dialogu, dowolny zapis
+  inline — więc renderer przebudowuje się dopiero wtedy, gdy odczyt naprawdę dał inny kolor. Sam
+  strażnik jest tańszy niż dawna bezwarunkowa przebudowa: jeden `getComputedStyle`, bez sondy 1×1
+  i bez arytmetyki OKLab.
+
+  W rdzeniu doszły `readBackdropLead()` (sam kolor wiodący, wydzielony z `resolveBackdropColors()`)
+  i `observeBackdropTheme()` (nasłuch razem z odpięciem). Oba porty wołają to samo, bo rozjazd
+  znaczyłby, że ta sama sekcja reaguje na motyw inaczej w Angularze niż w Reakcie.
+
+- Updated dependencies [f615e93]
+- Updated dependencies [f615e93]
+- Updated dependencies [f615e93]
+- Updated dependencies [f615e93]
+- Updated dependencies [c1f8885]
+- Updated dependencies [f615e93]
+- Updated dependencies [c1f8885]
+- Updated dependencies [ce34ab3]
+- Updated dependencies [a1c5468]
+- Updated dependencies [0daa856]
+  - @konce-pt/backdrop@0.8.5
+  - @konce-pt/chat@0.8.5
+  - @konce-pt/icons@0.8.5
+  - @konce-pt/i18n@0.8.5
+  - @konce-pt/mention@0.8.5
+  - @konce-pt/chart@0.8.5
+  - @konce-pt/datetime@0.8.5
+  - @konce-pt/map@0.8.5
+  - @konce-pt/roadmap@0.8.5
+  - @konce-pt/table@0.8.5
+
 ## 0.8.3
 
 ### Patch Changes

package/chat/src/lib/llms.txt

@@ -0,0 +1,160 @@
+# KptChat (kpt-chat, kpt-chat-message, kpt-chat-typing, kpt-chat-composer, kpt-chat-dock)
+
+A conversation: a grouped message list, a typing indicator, a composer and a floating dock in the
+corner of the screen. The row-building core — grouping, day separators, send-status arithmetic —
+lives in `@konce-pt/chat`: plain TypeScript, tested, shared with the React port.
+
+Import: `import { KptChat, KptChatComposer, KptChatDock, KptChatMessage, KptChatTyping } from '@konce-pt/angular/chat';`
+
+The library covers presentation and the local state of the list. Transport — a socket, HTTP, retry
+with backoff — stays in the application: the component takes messages and only reports `(retry)`
+and `(loadMore)`.
+
+## KptChat — inputs / outputs
+- `messages: readonly KptChatMessage<T>[]` — **in chronological order**; the component does not sort
+- `currentUser: string` — the author id treated as "me": those messages go right and carry a status
+- `groupGapMs: number` (default `KPT_CHAT_GROUP_GAP_MS`, 5 min) — the silence that breaks a group
+- `unreadFrom: string | null` — the id of the first unread message; the divider goes above it
+- `offline: boolean` — the warning strip with a count of messages waiting to be sent
+- `typing: readonly KptChatAuthor[]` — who is typing right now
+- `autoScroll: boolean` (default true), `actions: boolean`, `emptyLabel: string`
+- `reactionOptions: readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) — passed to the bubbles
+- `(retry)`, `(reply)` → `KptChatMessage<T>`; `(react)` → `KptChatReactEvent<T>` (`{ message, emoji }`);
+  `(quoted)` → `KptChatReplyRef`; `(loadMore)` → `void`, fired when the viewport reaches the top
+
+## Example
+    <kpt-chat
+      [messages]="messages()"
+      currentUser="me"
+      [typing]="typing()"
+      [offline]="offline()"
+      (retry)="resend($event)"
+      (loadMore)="loadOlder()"
+    />
+    <kpt-chat-composer allowAttachments [offline]="offline()" (send)="onSend($event)" />
+
+The composer is a sibling, not a slot: a read-only conversation (an archive, a preview) should not
+have to carry a text field it never shows.
+
+## Custom bubble content
+An `<ng-template>` inside `<kpt-chat>` replaces the bubble's text; the context is the message as
+`$implicit` and the whole row as `row`. The bubble, its grouping and its meta row stay in place —
+only the content is yours.
+
+    <kpt-chat [messages]="messages()" currentUser="me">
+      <ng-template let-message><kpt-card>{{ message.data.title }}</kpt-card></ng-template>
+    </kpt-chat>
+
+## KptChatMessage — the bubble on its own
+Works with a whole `[message]` object or with single inputs (`author`, `text`, `time`, `status`,
+`attachments`, `reactions`, `replyTo`), and takes projected content, so it renders anything.
+- `align`: 'start' | 'end' — someone else's message versus your own
+- `variant`: 'neutral' | 'primary' | 'solid' | 'ghost' | 'system'
+- `position`: 'single' | 'first' | 'middle' | 'last' — the place in a group
+- `showAuthor` / `showAvatar` / `showMeta` / `tail` / `actions`: boolean
+- `reactionOptions`: `readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) — the picker set
+
+The default variant follows the alignment: your own message gets the full `solid`, someone else's
+gets `neutral`. The theme is monochrome, so the difference between bubbles is lightness, not hue —
+`--kpt-color-primary-subtle` has exactly the lightness of `--kpt-color-muted`, which would make the
+two sides indistinguishable. For a quieter list set `variant="primary"` by hand.
+
+## Bubble actions: reply and react
+`actions` puts two buttons beside the bubble, shown on hover and on focus. The arrow emits
+`(reply)` with the whole message — `replyRefFrom()` from `@konce-pt/chat` turns it into the
+`replyTo` the composer's quote bar wants. The smiley opens a picker of five reactions (like, heart,
+smile, wow, sad — `KPT_CHAT_REACTIONS`, overridable through `reactionOptions`) and emits `(react)`
+with the chosen emoji.
+
+Neither one writes to the model: the library says what was clicked, the application decides what
+the conversation looks like afterwards. `toggleReaction(message.reactions, emoji)` does that
+arithmetic — it adds the reaction, takes it back on a second click and drops an entry that reaches
+zero, keeping the order of the rest.
+
+    (reply)="replyTo.set(replyRefFrom($event))"
+    (react)="onReact($event)"   // toggleReaction(item.reactions, $event.emoji)
+
+The picker closes on Escape, on a click outside and on picking; an option already given is marked
+`aria-pressed`, so it is visible which one the next click takes back. The retry arrow of a failed
+message takes the place of both — a message that has not gone out has nothing to reply to yet.
+
+## Grouping is what the shape is made of
+`position` decides which corner collapses, which bubble wears the tail, carries the avatar and shows
+the clock. Inside a group the corner on the sender's side drops to `--kpt-radius-sm`, so the bubbles
+read as one utterance. `kpt-chat` gets all of it from `buildChatRows()`; set it by hand only when
+you build the list yourself.
+
+A group breaks on a different author, a gap longer than `groupGapMs`, a calendar-day boundary, a
+system message and the unread divider.
+
+The bubble that wears the tail has a **square** bottom corner on that side — a rounded one curved
+away from the tail and the list background showed through the gap, which made the tail read as a
+separate arrow stuck next to the bubble rather than a part of it. Bubbles without a tail keep the
+rounded corner.
+
+## One day pill, not a stack of them
+The separators in the list travel with the content; which day the view is standing in is told by one
+pill floating over the list (`.kpt-chat__day`, `aria-hidden`, outside the scrolling area). Sticky
+separators looked right until the first collision: every next one pinned to the same edge, so a stack
+of frames grew up there and the older, wider pills stuck out from behind the newest.
+
+On every scroll (and after every re-render and resize) the component measures the separators, the
+unread divider and the system notices, hands the rectangles to `chatDayIndicator()` from
+`@konce-pt/chat` and swaps the pill's text. A centred label driving into the pill's band puts the
+pill out — it is the pill that yields, never the content — and with a separator that is also the
+handover, since the arriving "Today" says the same thing. Bubbles are not blockers: a pill over an
+utterance is the normal chat picture. The pill keeps its last label while it is out, so its band does
+not change height under the script that measures it.
+
+## An unsent message must be able to say so
+`status: 'failed'` outlines the bubble with `--kpt-color-danger-border` and puts a retry arrow
+**outside** it, on the outer side of the list. That bubble also shows its meta row even in the
+middle of a group — the arrow with nothing to explain it would be a mystery.
+Statuses: `sending`, `sent`, `delivered`, `read` (the same double check, in the accent colour) and
+`failed`. Out-of-order acks are what `mergeStatus()` from `@konce-pt/chat` is for.
+
+## KptChatComposer
+`[(value)]`, `placeholder`, `disabled`, `offline`, `allowAttachments`, `maxRows` (default 6),
+`enterToSend` (default true), `[(replyTo)]`, `(send)` → `{ text, files, replyTo }`, `(typing)`.
+Enter sends, Shift+Enter breaks the line; `enterToSend=false` swaps the two. The field grows with
+the content up to `maxRows` and then scrolls.
+
+It is **not** a Signal Forms control and will not become one: it never enters a form, has no
+`touched`/`invalid` state, and its value disappears on send. `model('')` describes that honestly.
+
+## KptChatDock
+`[(open)]`, `position` ('bottom-end' | 'bottom-start'), `unread`, `header`, `icon`, `width`,
+`offset` (distance from the corner, both axes, default `--kpt-space-6`).
+
+## Sharing the corner with kpt-scroll-top
+`kpt-scroll-top` pins itself to the same spot with the same `--kpt-z-overlay`, and it would swallow
+the chat FAB whole — only the unread badge would stick out, and the button could not be clicked.
+The stylesheet resolves it by itself: when a `bottom-end` dock is on the page, the scroll-top button
+steps **aside** (`:root:has()` shifts it left by the width of the FAB plus a gap). Sideways, not up,
+because the conversation panel stands above the FAB — moving it up would trade one collision for a
+worse one, with the button landing on the messages.
+It applies to `bottom-end` only, and it measures from the default offset: an application that sets
+`offset` positions the scroll-top button itself.
+The FAB is `kpt-fab` — the dock uses it, it does not replace it. The panel content is projected, so
+the dock knows nothing about messages. Opening moves focus to the composer, `Escape` closes and
+returns focus to the FAB. Below `--kpt-breakpoint-sm` the panel goes full-screen.
+
+    <kpt-chat-dock [(open)]="open" [unread]="unread()" header="Support">
+      <kpt-chat [messages]="messages()" currentUser="me" />
+      <kpt-chat-composer (send)="onSend($event)" />
+    </kpt-chat-dock>
+
+## Accessibility
+The list is `role="log"` with `aria-live="polite"`, so a new message is announced without cutting
+off what is being read. Each bubble is an `article` labelled with author, time and status — content
+alone would say nothing about who wrote it or whether it was sent. The typing indicator is
+`role="status"`; under `prefers-reduced-motion` the dots stop bouncing and pulse instead — they are
+the only carrier of "someone is typing", so switching them off entirely would remove the message.
+
+## Tokens
+Bubble `--kpt-color-muted` (incoming) / `--kpt-color-primary` + `--kpt-color-on-primary` (own);
+failed `--kpt-color-danger-subtle` + `--kpt-color-danger-border`; offline strip
+`--kpt-color-warning-subtle`; the day pill `--kpt-color-surface-raised` + a border and
+`--kpt-elevation-1` (the same look in the list and floating above it — the floating one travels over
+the bubbles and has to stand apart from them); dock `--kpt-elevation-3`
+and `--kpt-z-overlay`.