@konce-pt/react 0.8.3 → 0.9.0

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
@@ -393,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

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/button/button.d.ts

@@ -1,8 +1,8 @@
 import { type ComponentPropsWithRef } from 'react';
 import type { AsChildProps, KptHostProps } from '../internal/types.ts';
-export type KptButtonVariant = 'filled' | 'tonal' | 'outline' | 'text' | 'danger';
-export type KptButtonSize = 'sm' | 'md' | 'lg';
-export interface KptButtonProps extends ComponentPropsWithRef<'button'>, AsChildProps {
+export type KptButtonVariant = 'filled' | 'elevated' | 'tonal' | 'outline' | 'text' | 'link' | 'danger' | 'success' | 'warning' | 'info';
+export type KptButtonSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export interface KptButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'href'>, AsChildProps {
     /** Wariant wizualny. */
     variant?: KptButtonVariant;
     /** Rozmiar. */
@@ -11,17 +11,33 @@ export interface KptButtonProps extends ComponentPropsWithRef<'button'>, AsChild
     loading?: boolean;
     /** Pełna szerokość kontenera. */
     fullWidth?: boolean;
+    /** Nazwa ikony wiodącej z rejestru (`KptIconRegistry`). */
+    icon?: string;
+    /** Nazwa ikony zamykającej — zwykle znacznik kierunku, nie akcja. */
+    iconEnd?: string;
+    /** Klasa dokładana do ikony wiodącej; obok stałego haka `.kpt-button__icon`. */
+    iconClassName?: string;
+    iconEndClassName?: string;
+    /** Podany adres zamienia `<button>` na `<a>`. Ignorowany przy `asChild`. */
+    href?: string;
+    target?: string;
+    rel?: string;
     /** Propsy wrappera hosta (`.kpt-button-host`). `className` i `ref` idą na `<button>`. */
     hostProps?: KptHostProps<'span'>;
 }
 /**
  * Przycisk Koncept UI. Renderuje natywny `<button>` (semantyka + submit formularza)
- * w hoście `.kpt-button-host` — dwa poziomy DOM, dokładnie jak w porcie Angulara,
- * bo host niesie własne style (`display: inline-flex`, wariant pełnej szerokości).
+ * albo `<a>`, gdy podasz `href` — w hoście `.kpt-button-host`, czyli dwa poziomy DOM,
+ * dokładnie jak w porcie Angulara, bo host niesie własne style.
+ *
+ * Ikonę można podać nazwą (`icon`/`iconEnd`) albo wstawić w `children` — oba sposoby
+ * dostają ten sam odstęp i tę samą skalę. Przy `loading` spinner zajmuje miejsce ikony wiodącej.
  *
  * @example
  * <KptButton onClick={save}>Zapisz</KptButton>
- * <KptButton variant="outline" size="sm">Anuluj</KptButton>
+ * <KptButton icon="device-floppy" onClick={save}>Zapisz</KptButton>
+ * <KptButton iconEnd="chevron-right" variant="outline">Dalej</KptButton>
+ * <KptButton variant="link" href="/docs">Dokumentacja</KptButton>
  * <KptButton asChild><a href="/docs">Dokumentacja</a></KptButton>
  */
-export declare function KptButton({ variant, size, type, loading, fullWidth, disabled, asChild, hostProps, className, children, ...rest }: Readonly<KptButtonProps>): import("react").JSX.Element;
+export declare function KptButton({ variant, size, type, loading, fullWidth, disabled, asChild, icon, iconEnd, iconClassName, iconEndClassName, href, target, rel, hostProps, className, children, ...rest }: Readonly<KptButtonProps>): import("react").JSX.Element;

package/dist/button/button.js

@@ -2,22 +2,28 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { isValidElement } from 'react';
 import { cn } from "../internal/cn.js";
 import { renderAsChild } from "../internal/slot.js";
+import { KptIcon } from "../icon/icon.js";
 /**
  * Przycisk Koncept UI. Renderuje natywny `<button>` (semantyka + submit formularza)
- * w hoście `.kpt-button-host` — dwa poziomy DOM, dokładnie jak w porcie Angulara,
- * bo host niesie własne style (`display: inline-flex`, wariant pełnej szerokości).
+ * albo `<a>`, gdy podasz `href` — w hoście `.kpt-button-host`, czyli dwa poziomy DOM,
+ * dokładnie jak w porcie Angulara, bo host niesie własne style.
+ *
+ * Ikonę można podać nazwą (`icon`/`iconEnd`) albo wstawić w `children` — oba sposoby
+ * dostają ten sam odstęp i tę samą skalę. Przy `loading` spinner zajmuje miejsce ikony wiodącej.
  *
  * @example
  * <KptButton onClick={save}>Zapisz</KptButton>
- * <KptButton variant="outline" size="sm">Anuluj</KptButton>
+ * <KptButton icon="device-floppy" onClick={save}>Zapisz</KptButton>
+ * <KptButton iconEnd="chevron-right" variant="outline">Dalej</KptButton>
+ * <KptButton variant="link" href="/docs">Dokumentacja</KptButton>
  * <KptButton asChild><a href="/docs">Dokumentacja</a></KptButton>
  */
-export function KptButton({ variant = 'filled', size = 'md', type = 'button', loading = false, fullWidth = false, disabled = false, asChild = false, hostProps, className, children, ...rest }) {
+export function KptButton({ variant = 'filled', size = 'md', type = 'button', loading = false, fullWidth = false, disabled = false, asChild = false, icon, iconEnd, iconClassName, iconEndClassName, href, target, rel, hostProps, className, children, ...rest }) {
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
     const isDisabled = disabled || loading;
-    // Zawartość jest identyczna w obu trybach — w `asChild` podmieniamy tylko element
+    // Zawartość jest identyczna we wszystkich trybach — w `asChild` podmieniamy tylko element
     // zewnętrzny, nie strukturę środka, żeby SCSS (`__spinner`, `__content`) dalej działał.
-    const content = (_jsxs(_Fragment, { children: [loading ? _jsx("span", { className: "kpt-button__spinner", "aria-hidden": "true" }) : null, _jsx("span", { className: "kpt-button__content", children: asChildContent(asChild, children) })] }));
+    const content = (_jsxs(_Fragment, { children: [loading ? (_jsx("span", { className: "kpt-button__spinner", "aria-hidden": "true" })) : icon ? (_jsx(KptIcon, { className: cn('kpt-button__icon', iconClassName), name: icon })) : null, _jsx("span", { className: "kpt-button__content", children: asChildContent(asChild, children) }), iconEnd ? (_jsx(KptIcon, { className: cn('kpt-button__icon', 'kpt-button__icon--end', iconEndClassName), name: iconEnd })) : null] }));
     const buttonProps = {
         className: cn('kpt-button', loading && 'kpt-button--loading', className),
         'data-variant': variant,
@@ -27,13 +33,31 @@ export function KptButton({ variant = 'filled', size = 'md', type = 'button', lo
         'aria-busy': loading || undefined,
         ...rest,
     };
-    return (_jsx("span", { className: cn('kpt-button-host', fullWidth && 'kpt-button-host--full', hostClassName), ...hostRest, children: asChild && isValidElement(children) ? (renderAsChild(children, { ...buttonProps, ...disabledProps(children, isDisabled) }, content)) : (_jsx("button", { type: type, disabled: isDisabled, ...buttonProps, children: content })) }));
+    return (_jsx("span", { className: cn('kpt-button-host', fullWidth && 'kpt-button-host--full', hostClassName), ...hostRest, children: renderInner({ asChild, children, buttonProps, content, href, target, rel, type, isDisabled }) }));
+}
+/**
+ * Element wewnętrzny. `asChild` ma pierwszeństwo przed `href` — kto podstawia własny
+ * element, ten decyduje o znaczniku.
+ */
+function renderInner(args) {
+    const { asChild, children, buttonProps, content, href, target, rel, type, isDisabled } = args;
+    if (asChild && isValidElement(children)) {
+        return renderAsChild(children, { ...buttonProps, ...disabledProps(children, isDisabled) }, content);
+    }
+    if (href !== undefined) {
+        return (_jsx("a", { 
+            // Wyłączony odnośnik traci `href`, a nie tylko dostaje atrybut — inaczej dałoby się go
+            // kliknąć i wejść na niego z klawiatury.
+            href: isDisabled ? undefined : href, target: target, 
+            // `target="_blank"` bez `rel` to wektor na `window.opener` — dokładamy domyślne.
+            rel: rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined), "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : undefined, ...buttonProps, children: content }));
+    }
+    return (_jsx("button", { type: type, disabled: isDisabled, ...buttonProps, children: content }));
 }
 /**
  * Stan wyłączenia dla podstawionego elementu. Natywny `<button>` dostaje `disabled`
  * (SCSS stylizuje `:disabled`); każdy inny element — `aria-disabled`, bo `disabled`
- * nie ma tam znaczenia. Element bez `:disabled` nie dostanie wyglądu wyłączonego,
- * więc `asChild` + `disabled` to świadomie ograniczone połączenie.
+ * nie ma tam znaczenia.
  */
 function disabledProps(child, isDisabled) {
     if (!isDisabled)