@konce-pt/react 0.8.2 → 0.8.5

package/README.md

@@ -169,9 +169,9 @@ Data table with sorting, filtering, pagination and a custom cell:
 | **Navigation** | `KptTabs`, `KptAccordion`, `KptBreadcrumb`, `KptStepper`, `KptMenu`, `KptMenubar`, `KptMegamenu`, `KptContextMenu` |
 | **Data** | `KptDataTable`, `KptPaginator`, `KptTree`, `KptTimeline`, `KptCarousel`, `KptDataView`, `KptPickList`, `KptOrderList`, `KptGalleria`, `KptMeterGroup` |
 | **Feedback & overlay** | `KptAlert`, `KptDialog`, `kptToast` + `KptToastContainer`, `KptTooltip`, `KptPopover`, `KptDrawer`, `KptBottomSheet`, `kptConfirm`, `KptBadge`, `KptChip`, `KptAvatar`, `KptAvatarGroup`, `KptSpinner`, `KptProgress`, `KptSkeleton`, `KptEmpty`, `KptImage`, `KptAuth` |
-| **Subpaths** | `@konce-pt/react/charts` (`KptChart`), `/roadmap` (`KptRoadmap`), `/grid` (`KptGrid`, `KptCol`, `KptFlex`), `/map` (`KptMap` + legend, POI card, search), `/icons` (full Tabler set) |
+| **Subpaths** | `@konce-pt/react/charts` (`KptChart`), `/chat` (`KptChat`, `KptChatMessage`, `KptChatTyping`, `KptChatComposer`, `KptChatDock`), `/roadmap` (`KptRoadmap`), `/grid` (`KptGrid`, `KptCol`, `KptFlex`), `/map` (`KptMap` + legend, POI card, search), `/icons` (full Tabler set) |
 
-The heavy pieces (charts, roadmap, maps, the full icon set) live in subpaths on purpose, so the core
+The heavy pieces (charts, chat, roadmap, maps, the full icon set) live in subpaths on purpose, so the core
 entry point stays small. Every component ships an `llms.txt` API sheet next to its source.
 
 ## Theming
@@ -275,6 +275,9 @@ the Angular port.
 - **`llms.txt`** — LLM-friendly API sheets per component, shipped inside the package; the
   package-wide sheet lives at [ui.konce.pt/llms/react/llms.txt](https://ui.konce.pt/llms/react/llms.txt)
   (PL mirror: [llms-pl.txt](https://ui.konce.pt/llms/react/llms-pl.txt)).
+- **Security scanners** — Socket.dev and similar tools flag i18n keys as domain names
+  (`.email`, `.today` and friends are real TLDs) and the map's default endpoints; the
+  [project sheet](https://ui.konce.pt/llms.txt) explains each alert under "Security scanners".
 - Repository: [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui)
 
 ## License
@@ -390,8 +393,8 @@ Angulara.
 ### Komponenty (80+)
 
 Formularze, przyciski i akcje, layout, nawigacja, dane (z flagową `KptDataTable`), feedback
-i overlay — pełna lista w tabeli powyżej. Ciężkie rzeczy (wykresy, roadmapa, mapy, pełny Tabler)
-siedzą w subpathach `@konce-pt/react/{charts,roadmap,grid,map,icons}`, żeby nie obciążać rdzenia.
+i overlay — pełna lista w tabeli powyżej. Ciężkie rzeczy (wykresy, czat, roadmapa, mapy, pełny Tabler)
+siedzą w subpathach `@konce-pt/react/{charts,chat,roadmap,grid,map,icons}`, żeby nie obciążać rdzenia.
 Każdy komponent ma obok źródła plik `llms.txt` z opisem API.
 
 ### Dokumentacja
@@ -401,6 +404,10 @@ Playground z demami: [ui.konce.pt/react](https://ui.konce.pt/react). Opisy API d
 [`llms-pl.txt`](https://ui.konce.pt/llms/react/llms-pl.txt) (PL). Repozytorium:
 [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui).
 
+Alerty skanerów łańcucha dostaw (Socket.dev i podobne) — klucze i18n czytane jak domeny
+oraz domyślne endpointy mapy — omawia sekcja „Skanery bezpieczeństwa" w
+[arkuszu projektu](https://ui.konce.pt/llms-pl.txt).
+
 ### Licencja
 
 MIT © konce.pt

package/dist/backdrop/backdrop.d.ts

@@ -0,0 +1,79 @@
+import { type ComponentPropsWithRef } from 'react';
+import { type KptBackdropAnchor, type KptBackdropEffect } from '@konce-pt/backdrop';
+export type { KptBackdropAnchor, KptBackdropEffect } from '@konce-pt/backdrop';
+export interface KptBackdropProps extends ComponentPropsWithRef<'div'> {
+    /** Rysowany efekt. */
+    effect?: KptBackdropEffect;
+    /** Tło sekcji. Puste bierze `--kpt-color-surface`. */
+    background?: string;
+    /** Tempo; 1 to spokojne tempo obu efektów, 0 zatrzymuje obraz. */
+    speed?: number;
+    /** Ziarno losowania — ta sama wartość daje ten sam układ kwadratów i ten sam przebieg wstęgi. */
+    seed?: number;
+    /** Zatrzymuje animację, zostawiając ostatnią klatkę. */
+    paused?: boolean;
+    /**
+     * Przenosi barwy wpisane na sztywno na powierzchnię bieżącego motywu: czerń dobrana do białego
+     * tła staje się bielą, gdy tło jest ciemne. Rusza wyłącznie jasność — odcień i nasycenie
+     * zostają, więc barwa marki nie zmienia się w inną barwę.
+     *
+     * Dotyczy `color`, `colors` i `background`, ale tylko wtedy, gdy podano je literałem. Prop pusty
+     * bierze token, a zapis z `var()` sam po token sięga — jedno i drugie już idzie za motywem
+     * i adaptacja odwróciłaby je drugi raz.
+     */
+    adaptive?: boolean;
+    /**
+     * `signal-grid`: kolor kwadratów — dowolny zapis CSS, także sięgający po tokeny, np.
+     * `color-mix(in oklab, #5b8af2, var(--kpt-color-surface) 30%)`. Taki zapis przelicza się przy
+     * zmianie motywu; literał zostaje literałem. Puste bierze `--kpt-color-primary`.
+     */
+    color?: string;
+    /** `signal-grid`: przy której krawędzi siatka jest najgęstsza. */
+    anchor?: KptBackdropAnchor;
+    /** `signal-grid`: bok kwadratu (px). */
+    cell?: number;
+    /** `signal-grid`: odstęp między kwadratami (px). */
+    gap?: number;
+    /** `signal-grid`: udział zapalonych komórek przy kotwicy, 0–1. */
+    density?: number;
+    /** `signal-grid`: jak szybko siatka gaśnie ku przeciwnej krawędzi. */
+    falloff?: number;
+    /**
+     * `wave`: rampa barw, po której przesuwa się wstęga — każdy przystanek dowolnym zapisem CSS.
+     * Zamknięta w pętlę, więc ostatnia barwa wraca do pierwszej. Pusta bierze `--kpt-color-primary`
+     * i dwie barwy wyprowadzone z niego obrotem odcienia — paleta biblioteki jest neutralna, więc
+     * domyślna wstęga jest jednobarwna i przygaszona. Po kolory sięga się tu, nie do tokenów
+     * statusowych. Zapis może sięgać po tokeny i wtedy idzie za motywem. Przystanek, którego
+     * przeglądarka nie uznaje za kolor, wypada z rampy; gdy wypadną wszystkie, zostaje rampa
+     * domyślna.
+     */
+    colors?: readonly string[];
+    /** `wave`: kąt, pod jakim prąd przecina kadr (stopnie); 0 to poziomo w prawo. */
+    rotation?: number;
+    /** `wave`: szerokość wstęgi jako ułamek wysokości kadru. */
+    band?: number;
+    /** `wave`: jak mocno faluje linia środkowa. Zero zatrzymuje falowanie, nie barwy. */
+    amplitude?: number;
+    /** Propsy warstwy z treścią (`.kpt-backdrop__content`). */
+    contentProps?: ComponentPropsWithRef<'div'>;
+}
+/**
+ * Dekoracyjna warstwa tła dla sekcji: komponent obejmuje treść i maluje pod nią animowany canvas.
+ * Sięga się po niego tam, gdzie płaska powierzchnia wygląda na niedokończoną, a wideo albo duży
+ * obraz kosztowałyby transfer i nie poszłyby za motywem.
+ *
+ * Komponent jest opakowaniem: canvas leży pod spodem, a dzieci idą warstwę wyżej i zachowują się
+ * zwyczajnie. Rysowanie stoi, gdy nie ma czego oglądać — sekcja poza ekranem, karta w tle,
+ * `paused`, `speed` równe zeru albo ograniczony ruch w systemie; wtedy zostaje jedna statyczna
+ * klatka zamiast pustki, bo efekt jest częścią kompozycji, nie ozdobą.
+ *
+ * Rysowanie i cała matematyka siedzą w `@konce-pt/backdrop`, wspólnym z portem Angulara —
+ * ten komponent to sam cykl życia.
+ *
+ * @example
+ * <KptBackdrop effect="wave" rotation={18} colors={['#5b8af2', '#a86df2', '#f25b9e']}>
+ *   <h1>Build your app from the first prompt</h1>
+ *   <KptButton>Get started</KptButton>
+ * </KptBackdrop>
+ */
+export declare function KptBackdrop({ effect, background, speed, seed, paused, adaptive, color, anchor, cell, gap, density, falloff, colors, rotation, band, amplitude, contentProps, className, style, children, ...rest }: Readonly<KptBackdropProps>): import("react").JSX.Element;

package/dist/backdrop/backdrop.js

@@ -0,0 +1,195 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { KPT_BACKDROP_MAX_DPR, KPT_BACKDROP_MAX_STEP, KPT_SIGNAL_GRID_CELL, KPT_SIGNAL_GRID_DENSITY, KPT_SIGNAL_GRID_FALLOFF, KPT_SIGNAL_GRID_GAP, KPT_WAVE_AMPLITUDE, KPT_WAVE_BAND, KPT_WAVE_ROTATION, adaptBackdropValue, createBackdropRenderer, observeBackdropTheme, readBackdropInk, readBackdropLead, readBackdropSurface, resolveBackdropColors, } from '@konce-pt/backdrop';
+import { cn } from "../internal/cn.js";
+import { isDevBuild } from "../internal/dev.js";
+const EMPTY = [];
+/**
+ * Dekoracyjna warstwa tła dla sekcji: komponent obejmuje treść i maluje pod nią animowany canvas.
+ * Sięga się po niego tam, gdzie płaska powierzchnia wygląda na niedokończoną, a wideo albo duży
+ * obraz kosztowałyby transfer i nie poszłyby za motywem.
+ *
+ * Komponent jest opakowaniem: canvas leży pod spodem, a dzieci idą warstwę wyżej i zachowują się
+ * zwyczajnie. Rysowanie stoi, gdy nie ma czego oglądać — sekcja poza ekranem, karta w tle,
+ * `paused`, `speed` równe zeru albo ograniczony ruch w systemie; wtedy zostaje jedna statyczna
+ * klatka zamiast pustki, bo efekt jest częścią kompozycji, nie ozdobą.
+ *
+ * Rysowanie i cała matematyka siedzą w `@konce-pt/backdrop`, wspólnym z portem Angulara —
+ * ten komponent to sam cykl życia.
+ *
+ * @example
+ * <KptBackdrop effect="wave" rotation={18} colors={['#5b8af2', '#a86df2', '#f25b9e']}>
+ *   <h1>Build your app from the first prompt</h1>
+ *   <KptButton>Get started</KptButton>
+ * </KptBackdrop>
+ */
+export function KptBackdrop({ effect = 'signal-grid', background = '', speed = 1, seed = 0, paused = false, adaptive = false, color = '', anchor = 'right', cell = KPT_SIGNAL_GRID_CELL, gap = KPT_SIGNAL_GRID_GAP, density = KPT_SIGNAL_GRID_DENSITY, falloff = KPT_SIGNAL_GRID_FALLOFF, colors = EMPTY, rotation = KPT_WAVE_ROTATION, band = KPT_WAVE_BAND, amplitude = KPT_WAVE_AMPLITUDE, contentProps, className, style, children, ...rest }) {
+    const host = useRef(null);
+    const canvas = useRef(null);
+    const context = useRef(null);
+    const renderer = useRef(null);
+    const size = useRef({ width: 0, height: 0 });
+    /** Zegar animacji w sekundach — w refie, żeby przebudowa renderera nie cofała obrazu. */
+    const clock = useRef(0);
+    /** Kolor wiodący, z którym zbudowany jest bieżący renderer — punkt odniesienia dla zmiany motywu. */
+    const lead = useRef('');
+    /** Ostatnio zgłoszony zestaw odrzuconych barw — żeby nie powtarzać tego samego ostrzeżenia. */
+    const reported = useRef('');
+    /** Tło po adaptacji. Puste znaczy „nie ma czego podmieniać" i wtedy liczy się samo `background`. */
+    const [adapted, setAdapted] = useState('');
+    /**
+     * Ton i kolor treści dobrane do malowanego tła. Puste znaczy „sekcja nie ma własnego tła"
+     * i wtedy treść zostaje przy `--kpt-color-on-surface` ze stylu.
+     */
+    const [ink, setInk] = useState({ tone: '', color: '' });
+    const rate = useRef(speed);
+    rate.current = speed;
+    const [onScreen, setOnScreen] = useState(true);
+    const [reduced, setReduced] = useState(false);
+    /** Licznik zmian motywu; podbicie każe przeliczyć kolory z tokenów na nowo. */
+    const [theme, setTheme] = useState(0);
+    const paint = useCallback(() => {
+        if (context.current)
+            renderer.current?.draw(context.current, clock.current);
+    }, []);
+    const measure = useCallback(() => {
+        const element = canvas.current;
+        if (!element)
+            return;
+        context.current ??= element.getContext('2d');
+        const rect = element.getBoundingClientRect();
+        const dpr = Math.min(globalThis.devicePixelRatio || 1, KPT_BACKDROP_MAX_DPR);
+        const width = Math.round(rect.width);
+        const height = Math.round(rect.height);
+        size.current = { width, height };
+        element.width = Math.round(width * dpr);
+        element.height = Math.round(height * dpr);
+        // Zapis width/height zeruje kontekst, więc skala musi wrócić po każdym pomiarze.
+        context.current?.setTransform(dpr, 0, 0, dpr, 0, 0);
+    }, []);
+    // Tablica barw przychodzi nowa przy każdym renderze rodzica, więc do zależności idzie jej treść.
+    const ramp = colors.join('|');
+    const list = useMemo(() => (ramp === '' ? EMPTY : ramp.split('|')), [ramp]);
+    // Każda zmiana wejść buduje renderer od nowa — zamiast doklejać ścieżki „co się zmieniło".
+    useEffect(() => {
+        // Kolory rozwiązuje się na canvasie, nie na hoście: sonda `var()` pisze inline style, a nasłuch
+        // motywu ogląda `style` hosta i jego przodków — zapis na hoście zapętliłby przebudowy.
+        const scope = canvas.current;
+        if (!scope)
+            return undefined;
+        measure();
+        const resolved = resolveBackdropColors(scope, color, list, adaptive);
+        lead.current = resolved.color;
+        const painted = adaptive ? adaptBackdropValue(background, readBackdropSurface(scope)) : background;
+        setAdapted(adaptive ? painted : '');
+        // Ton liczymy z tła, które sekcja naprawdę pomaluje — czyli już po adaptacji.
+        setInk(readBackdropInk(scope, painted));
+        // Efekt chodzi przy każdej zmianie wejść, więc ciągnięcie suwaka nad wadliwą rampą zasypałoby
+        // konsolę tym samym zdaniem — zgłaszamy dopiero zestaw inny niż poprzednio.
+        const rejected = resolved.invalid.join(', ');
+        if (rejected !== reported.current) {
+            reported.current = rejected;
+            if (rejected !== '' && isDevBuild()) {
+                console.warn(`[KptBackdrop] Pominięto barwy, których przeglądarka nie rozpoznaje: ${rejected}`);
+            }
+        }
+        const current = createBackdropRenderer({
+            effect,
+            color: resolved.color,
+            colors: resolved.colors,
+            anchor,
+            cell,
+            gap,
+            density,
+            falloff,
+            rotation,
+            band,
+            amplitude,
+            seed,
+        });
+        current.resize(size.current.width, size.current.height);
+        renderer.current = current;
+        paint();
+        return () => {
+            current.dispose();
+            renderer.current = null;
+        };
+    }, [effect, color, list, anchor, cell, gap, density, falloff, rotation, band, amplitude, seed, adaptive, background, theme, measure, paint]);
+    // Sam rozmiar nie zmienia ustawień, więc renderer zostaje — przelicza tylko geometrię.
+    useEffect(() => {
+        const element = canvas.current;
+        if (!element)
+            return undefined;
+        const observer = new ResizeObserver(() => {
+            const rect = element.getBoundingClientRect();
+            if (Math.round(rect.width) === size.current.width && Math.round(rect.height) === size.current.height)
+                return;
+            measure();
+            renderer.current?.resize(size.current.width, size.current.height);
+            paint();
+        });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [measure, paint]);
+    // Sekcja poza ekranem i karta w tle to ten sam przypadek: nie ma czego oglądać.
+    useEffect(() => {
+        const element = host.current;
+        if (!element)
+            return undefined;
+        const update = (visible) => setOnScreen(visible && !document.hidden);
+        const observer = new IntersectionObserver((entries) => update(entries.some((entry) => entry.isIntersecting)));
+        observer.observe(element);
+        const onTabSwitch = () => setOnScreen(!document.hidden);
+        document.addEventListener('visibilitychange', onTabSwitch);
+        return () => {
+            observer.disconnect();
+            document.removeEventListener('visibilitychange', onTabSwitch);
+        };
+    }, []);
+    useEffect(() => {
+        const query = matchMedia('(prefers-reduced-motion: reduce)');
+        setReduced(query.matches);
+        const onChange = (event) => setReduced(event.matches);
+        query.addEventListener('change', onChange);
+        return () => query.removeEventListener('change', onChange);
+    }, []);
+    // Zmiana motywu przestawia tokeny, a kolory renderera są już wyliczone — trzeba je odczytać
+    // na nowo. Nasłuch trafia też w zmiany niezwiązane z barwą, więc licznik podbija się dopiero
+    // wtedy, gdy odczyt naprawdę dał inny kolor.
+    useEffect(() => {
+        const element = host.current;
+        if (!element)
+            return undefined;
+        return observeBackdropTheme(element, () => {
+            const scope = canvas.current;
+            if (!scope)
+                return;
+            // Ten sam rachunek co w efekcie budującym — inaczej strażnik porównywałby wartość sprzed
+            // adaptacji z zapamiętaną po adaptacji i podbijałby licznik bez przerwy.
+            const next = adaptive ? adaptBackdropValue(color, readBackdropSurface(scope)) : color;
+            if (readBackdropLead(scope, next) === lead.current)
+                return;
+            setTheme((count) => count + 1);
+        });
+    }, [color, adaptive]);
+    useEffect(() => {
+        if (paused || reduced || !onScreen || speed <= 0)
+            return undefined;
+        let frame = 0;
+        let last = 0;
+        const tick = (now) => {
+            const step = last === 0 ? 0 : Math.min(now - last, KPT_BACKDROP_MAX_STEP);
+            last = now;
+            // Prędkość wchodzi w zegar, nie w fazę — suwak przyspiesza obraz zamiast go przeskakiwać.
+            clock.current += (step / 1000) * rate.current;
+            paint();
+            frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frame);
+    }, [paused, reduced, onScreen, speed, paint]);
+    const { className: contentClassName, ...contentRest } = contentProps ?? {};
+    /** Tło malowane na hoście: po adaptacji, jeśli jest, inaczej to, co podano. */
+    const surface = adapted || background;
+    return (_jsxs("div", { ref: host, className: cn('kpt-backdrop-host', className), "data-effect": effect, "data-tone": ink.tone || undefined, style: { ...(surface ? { background: surface } : null), ...(ink.color ? { color: ink.color } : null), ...style }, ...rest, children: [_jsx("canvas", { ref: canvas, className: "kpt-backdrop__canvas", "aria-hidden": "true" }), _jsx("div", { className: cn('kpt-backdrop__content', contentClassName), ...contentRest, children: children })] }));
+}

package/dist/backdrop/llms.txt

@@ -0,0 +1,132 @@
+# KptBackdrop (@konce-pt/react)
+
+A decorative background layer for a section: the component wraps your content and paints an
+animated canvas beneath it. You reach for it where a flat surface looks unfinished, and where
+a video or a large image would cost bandwidth and refuse to follow the theme.
+Children sit a layer above the canvas and behave normally.
+Import: `import { KptBackdrop } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-backdrop-host" data-effect="wave">
+      <canvas class="kpt-backdrop__canvas" aria-hidden="true"></canvas>
+      <div class="kpt-backdrop__content">…</div>
+    </div>
+
+## Props (shared)
+- `effect`: 'signal-grid' | 'wave' (default 'signal-grid')
+- `background`: string — the section background; empty takes `--kpt-color-surface`
+- `speed`: number (default 1) — 1 is the calm pace of either effect, 0 freezes the picture
+- `seed`: number (default 0) — the same value gives the same layout and the same sway
+- `paused`: boolean — stops the animation, leaving the last frame
+- `adaptive`: boolean — carries hardcoded colours onto the current theme's surface
+- `contentProps` — props for the `.kpt-backdrop__content` layer
+- `className`, `ref` and every other `<div>` prop go to `.kpt-backdrop-host`
+
+## Props (signal-grid)
+- `color`: string — the square colour, any CSS notation, tokens included; empty takes
+  `--kpt-color-primary`
+- `anchor`: 'left' | 'right' (default 'right') — the edge the grid is densest at
+- `cell`: number (default 5), `gap`: number (default 11) — the square and the space between, in px
+- `density`: number (default 0.8) — the share of lit cells at the anchor, 0–1
+- `falloff`: number (default 1.4) — how fast the grid fades towards the far edge
+
+## Props (wave)
+- `colors`: string[] — the colour ramp the current slides along, closed into a loop; every
+  stop takes any CSS notation, `color`'s rules exactly
+- `rotation`: number (default 12) — the angle the current crosses the frame at, in degrees
+- `band`: number (default 0.34) — the band's width as a fraction of the frame's height
+- `amplitude`: number (default 0.16) — how far the centre line sways
+
+A prop that does not belong to the current effect is simply not read.
+
+## Examples
+    <KptBackdrop effect="wave" rotation={18} colors={['#5B8AF2', '#A86DF2', '#F25B9E']}>
+      <h1>Build your app from the first prompt</h1>
+      <KptButton>Get started</KptButton>
+    </KptBackdrop>
+
+## The two effects
+`signal-grid` is a fine grid of squares that quietly twinkle, dense at one edge and fading to
+empty at the other; the gradient comes from **how many** squares are lit, not from opacity laid
+over an even grid. `wave` is one soft current of light with hues sliding along it and no hard edge
+anywhere; `rotation` turns it, `band` widens it, `amplitude` sways it.
+
+Without `colors` the wave's ramp is `--kpt-color-primary` plus two hues derived from it by
+rotation. The library's palette is neutral, so that default current is single-hued and muted.
+
+Every stop is put to the browser, so `oklch()`, `color-mix()`, `rgb()` and named colours are read
+the same as hex; alpha is dropped. A stop the browser refuses falls out of the ramp, and if every
+one of them falls out the default ramp takes over rather than the section going blank — a dev
+build says in the console which stops it dropped.
+
+## The same picture in both ports
+Everything that decides how it looks — the grid layout, the density ramp, the twinkle, the current
+and the colour ramp, plus the renderers themselves — lives in `@konce-pt/backdrop`, shared with
+the Angular port. This component is the lifecycle: `rAF`, `ResizeObserver`, `IntersectionObserver`,
+the reduced-motion query and the theme watch. The same props therefore give the
+same frame in either port.
+
+## Rest
+Drawing stops when there is nothing to watch: the section is off-screen, the tab is in the
+background, `paused` is set, `speed` is 0, or the system asks for reduced motion. What is left is
+a single static frame, not emptiness. `speed` feeds the clock rather than the phase, so a speed
+slider accelerates the picture instead of jumping it. A change of `colors` is tracked by content,
+not by array identity, so a fresh array from a parent render does not rebuild the renderer.
+
+## Accessibility
+The canvas carries `aria-hidden="true"` and `pointer-events: none` — it is decoration with no
+content and nothing to hit. Children keep their own roles and tab order.
+
+## Tokens
+`--kpt-color-primary` (squares and the default ramp), `--kpt-color-surface` (background),
+`--kpt-color-on-surface`. Section-wide overrides: `--kpt-backdrop-color`, `--kpt-backdrop-surface`.
+
+## Adaptive colours
+A literal stays put by design, which is right for a brand colour and wrong for a section meant to
+read in both themes. `adaptive` closes that gap: it carries `color`, `colors` and `background`
+onto the surface of the current theme, keeping each one's distance from that surface. Black picked
+for a white section comes out white on a near-black ground, and that white background comes out at
+the surface's own lightness. Only lightness moves — hue and chroma stay, so a brand colour keeps
+being that colour and only changes how light it is.
+
+It touches literals only. An empty input takes a token, and a value reaching through `var()`
+reaches a token too; both already follow the theme, and adapting them would turn them back again.
+Values written for the light theme are the assumption — the library keeps light in `:root` and
+dark as the override.
+
+## Content on a custom background
+The host paints `--kpt-color-surface` and lets content inherit `--kpt-color-on-surface`, which is
+right until the section gets a `background` of its own — then that token describes the page around
+it, not the ground the content actually sits on. A dark section in a light theme would come out
+black on black.
+
+So a section with its own background works out its own ink: the host sets `color` to match what it
+paints, and announces the result as `data-tone` (`light` for a light background, `dark` for a dark
+one). Text follows by inheritance; anything needing more than a text colour — buttons in the
+section, say — can hang its own tokens off the attribute:
+
+    :where(div.kpt-backdrop-host[data-tone='light']) .hero { --kpt-button-filled-bg: #15181a; }
+
+The tone is computed from the background the section really paints, so with `adaptive` on it
+matches the adapted value, not the one written in the template. A section without its own
+background announces nothing and content stays on `--kpt-color-on-surface`.
+
+## Theme
+Canvas does not expand `var()`, so the colour is read once and baked into the renderer — the
+component therefore watches for anything that can restyle the tokens under it and reads them
+again. `[data-theme="dark"]` is not tied to `:root`, so the watch covers `data-theme`, `class`
+and `style` on every ancestor from the host up to `<html>`, plus the `prefers-color-scheme` query
+for an application that keeps its dark tokens in a media query. A runtime override of
+`--kpt-color-primary` is picked up the same way as a theme switch. The renderer is rebuilt only
+when the colour actually came out different, so an unrelated class landing on `<html>` costs one
+cheap read and nothing else.
+
+Whether an explicit `color` or `colors` follows the theme is up to how it is written. A literal
+stays put — `#5b8af2` is `#5b8af2` in either theme, which is what someone spelling out a brand
+colour wants. An expression reaching for a token is resolved against the tree on every rebuild, so
+it moves with the theme on its own:
+
+    <KptBackdrop color="color-mix(in oklab, #5b8af2, var(--kpt-color-surface) 30%)">
+
+`var(--kpt-color-primary)` works the same way. A name that resolves to nothing falls back to the
+token for `color`, and drops out of the ramp for `colors`.

package/dist/chat/chat.d.ts

@@ -0,0 +1,53 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import type { KptChatAuthor, KptChatMessage as KptChatMessageModel, KptChatMessageRow, KptChatReactionOption, KptChatReplyRef } from '@konce-pt/chat';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+/** Wybór reakcji na wiadomości — komponent mówi, w co kliknięto, dopisanie należy do aplikacji. */
+export interface KptChatReactEvent<T = unknown> {
+    message: KptChatMessageModel<T>;
+    emoji: string;
+}
+export interface KptChatProps<T = unknown> extends Omit<ComponentPropsWithRef<'div'>, 'children'>, KptI18nOverrides {
+    /** Wiadomości w kolejności chronologicznej — komponent ich nie sortuje. */
+    messages?: readonly KptChatMessageModel<T>[];
+    /** `id` nadawcy uznawanego za „mnie": jego wiadomości idą na prawo i mają status. */
+    currentUser?: string;
+    /** Przerwa łamiąca grupę wiadomości jednego nadawcy. */
+    groupGapMs?: number;
+    /** `id` pierwszej nieprzeczytanej wiadomości — nad nią stanie dzielnik. */
+    unreadFrom?: string | null;
+    /** Brak połączenia: pasek u góry listy z liczbą wiadomości czekających na wysłanie. */
+    offline?: boolean;
+    /** Osoby piszące w tej chwili. */
+    typing?: readonly KptChatAuthor[];
+    /** Dosuwanie widoku do najnowszej wiadomości, dopóki użytkownik nie odjedzie w górę. */
+    autoScroll?: boolean;
+    /** Akcje bąbla pod kursorem: odpowiedz i zareaguj. */
+    actions?: boolean;
+    /** Zestaw wybieraka reakcji, przekazywany bąblom. Domyślnie pięć wbudowanych. */
+    reactionOptions?: readonly KptChatReactionOption[];
+    /** Własny komunikat pustej rozmowy. */
+    emptyLabel?: string;
+    onRetry?: (message: KptChatMessageModel<T>) => void;
+    onReply?: (message: KptChatMessageModel<T>) => void;
+    onReact?: (event: KptChatReactEvent<T>) => void;
+    onQuoted?: (quote: KptChatReplyRef) => void;
+    /** Przewinięcie na sam szczyt — moment na dociągnięcie starszych wiadomości. */
+    onLoadMore?: () => void;
+    /** Szablon treści bąbla — odpowiednik `<ng-template let-message>` z Angulara. */
+    renderMessage?: (message: KptChatMessageModel<T>, row: KptChatMessageRow<T>) => ReactNode;
+}
+/**
+ * Lista rozmowy — grupuje wiadomości, wstawia separatory dni i dzielnik nieprzeczytanych,
+ * trzyma widok przy dole i pokazuje pasek offline z liczbą wiadomości czekających na wysłanie.
+ *
+ * Sama logika wierszy mieszka w `@konce-pt/chat` (`buildChatRows`), więc port Angulara liczy ją
+ * tak samo. Komponent nie ma nic wspólnego z transportem: wiadomości dostaje, a `onRetry`
+ * i `onLoadMore` tylko zgłasza — ponowieniem wysyłki i dociąganiem historii zajmuje się aplikacja.
+ *
+ * Kompozytor (`KptChatComposer`) jest osobnym komponentem i stoi obok listy — dzięki temu
+ * czat bez pola wpisywania (podgląd, archiwum) nie wozi go ze sobą.
+ *
+ * @example
+ * <KptChat messages={messages} currentUser="me" typing={typing} onRetry={resend} />
+ */
+export declare function KptChat<T = unknown>({ messages, currentUser, groupGapMs, unreadFrom, offline, typing, autoScroll, actions, reactionOptions, emptyLabel, onRetry, onReply, onReact, onQuoted, onLoadMore, renderMessage, locale, dictionary, className, ...rest }: Readonly<KptChatProps<T>>): import("react").JSX.Element;