@konce-pt/react 0.11.2 → 0.14.0

package/dist/autocomplete/autocomplete.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
 import { cn } from "../internal/cn.js";
@@ -7,21 +8,37 @@ import { useControllableState } from "../internal/use-controllable-state.js";
 import { foldMentionText } from '@konce-pt/mention';
 import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
+import { KptSpeechButton } from "../speech/speech-button.js";
+import { useKptSpeechRecognition } from "../speech/use-speech-recognition.js";
 /**
- * Pole z podpowiedziami. Wartością jest wpisany tekst, nie wybrana opcja — podpowiedzi
+ * Pole z podpowiedziami. Wartością jest wpisany tekst, nie wybrana opcja - podpowiedzi
  * skracają pisanie, ale nie ograniczają wpisu, więc pole nadaje się też do wartości spoza listy.
  *
- * Wzorzec WAI-ARIA „combobox z listą”: fokus zostaje w polu, aktywną podpowiedź ogłasza
- * `aria-activedescendant`, a liczbę podpowiedzi (albo ich brak) — region `polite`. Dopasowanie
- * pomija wielkość liter i diakrytyki („lodz” znajduje „Łódź”).
+ * Wzorzec WAI-ARIA "combobox z listą": fokus zostaje w polu, aktywną podpowiedź ogłasza
+ * `aria-activedescendant`, a liczbę podpowiedzi (albo ich brak) - region `polite`. Dopasowanie
+ * pomija wielkość liter i diakrytyki ("lodz" znajduje "Łódź").
  *
  * @example
- * <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="Miasto…" />
+ * <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="Miasto..." />
  */
-export function KptAutocomplete({ options = [], value, defaultValue = '', onValueChange, invalid = false, touched, onTouch, disabled = false, className, onBlur, onFocus, onKeyDown, ref, id, 'aria-describedby': ariaDescribedBy, locale, dictionary, ...rest }) {
+export function KptAutocomplete({ options = [], value, defaultValue = '', onValueChange, invalid = false, touched, onTouch, disabled = false, readOnly = false, className, onBlur, onFocus, onKeyDown, ref, id, 'aria-describedby': ariaDescribedBy, locale, dictionary, speech = false, speechLang, speechColor, speechMode = 'replace', ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const field = useKptFieldA11y(id, 'kpt-autocomplete');
     const inputRef = useRef(null);
+    /** Kotwica nakładki w stanie (callback ref), nie `inputRef.current` czytane w renderze. */
+    const [anchor, setAnchor] = useState(null);
+    const setRefs = useMemo(() => composeRefs(inputRef, ref, setAnchor), [ref]);
+    // Podyktowana wartość wchodzi przez `onChange` pola, więc lista otwiera się jak po wpisaniu;
+    // słowa tymczasowe nie filtrują - nie ma ich w stanie. Bez `speech` kontroler nie tworzy sesji.
+    const mic = useKptSpeechRecognition({
+        enabled: speech,
+        target: inputRef,
+        lang: speechLang,
+        mode: speechMode,
+        continuous: speechMode !== 'replace',
+        disabled: disabled || readOnly,
+    });
+    const speechState = speech && mic.available ? (mic.listening ? 'listening' : 'idle') : undefined;
     const [current, setCurrent] = useControllableState({
         value,
         defaultValue,
@@ -29,7 +46,7 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
     });
     const [open, setOpen] = useState(false);
     const [activeIndex, setActiveIndex] = useState(-1);
-    /** Wpisano coś od ostatniego otwarcia — dopiero wtedy ogłaszamy liczbę podpowiedzi. */
+    /** Wpisano coś od ostatniego otwarcia - dopiero wtedy ogłaszamy liczbę podpowiedzi. */
     const [typed, setTyped] = useState(false);
     const showInvalid = invalid && (touched ?? true);
     const filtered = useMemo(() => {
@@ -55,6 +72,9 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
     }, [setCurrent]);
     const handleKeyDown = (event) => {
         onKeyDown?.(event);
+        // Tylko do odczytu: podpowiedzi się nie otwierają, a Escape nie czyści wartości.
+        if (readOnly)
+            return;
         if (event.key === 'ArrowDown') {
             event.preventDefault();
             setOpen(true);
@@ -63,7 +83,7 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
         else if (event.key === 'ArrowUp') {
             event.preventDefault();
             setOpen(true);
-            // Z pola (bez aktywnej) `↑` idzie na ostatnią podpowiedź.
+            // Z pola (bez aktywnej) `ArrowUp` idzie na ostatnią podpowiedź.
             setActiveIndex((index) => (index <= 0 ? filtered.length - 1 : index - 1));
         }
         else if (event.key === 'Enter') {
@@ -86,20 +106,21 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
             }
         }
     };
-    return (_jsxs("span", { className: "kpt-autocomplete-host", children: [_jsx("input", { ref: composeRefs(inputRef, ref), className: cn('kpt-autocomplete__input', className), type: "text", id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), role: "combobox", "aria-autocomplete": "list", autoComplete: "off", "aria-expanded": panelOpen, "aria-controls": panelOpen ? listId : undefined, "aria-activedescendant": activeOptionId, "aria-invalid": showInvalid || undefined, disabled: disabled, value: current, onChange: (event) => {
+    return (_jsxs("span", { className: "kpt-autocomplete-host", "data-speech": speechState, children: [_jsx("input", { ref: setRefs, className: cn('kpt-autocomplete__input', className), type: "text", id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), role: "combobox", "aria-autocomplete": "list", autoComplete: "off", "aria-expanded": panelOpen, "aria-controls": panelOpen ? listId : undefined, "aria-activedescendant": activeOptionId, "aria-invalid": showInvalid || undefined, "aria-readonly": readOnly || undefined, disabled: disabled, readOnly: readOnly, value: current, onChange: (event) => {
                     setCurrent(event.target.value);
                     setOpen(true);
                     setTyped(true);
                     setActiveIndex(-1);
                 }, onFocus: (event) => {
                     onFocus?.(event);
-                    setOpen(true);
+                    if (!readOnly)
+                        setOpen(true);
                 }, onBlur: (event) => {
                     onBlur?.(event);
                     setOpen(false);
                     setTyped(false);
                     onTouch?.();
-                }, onKeyDown: handleKeyDown, ...rest }), _jsx(KptOverlay, { open: panelOpen, anchor: inputRef.current, onClose: () => setOpen(false), matchAnchorWidth: true, withBackdrop: false, children: _jsx("ul", { className: "kpt-autocomplete__panel", role: "listbox", id: listId, "aria-label": rest['aria-label'], children: filtered.map((option, index) => (_jsx("li", { id: optionId(index), className: cn('kpt-autocomplete__option', index === activeIndex && 'is-active'), role: "option", "aria-selected": index === activeIndex, 
+                }, onKeyDown: handleKeyDown, ...rest }), speech ? (_jsx(KptSpeechButton, { listeningColor: speechColor, speech: mic, size: "sm", unsupported: "hide", disabled: disabled || readOnly, hostProps: { className: 'kpt-autocomplete__speech' } })) : null, _jsx(KptOverlay, { open: panelOpen, anchor: anchor, onClose: () => setOpen(false), matchAnchorWidth: true, withBackdrop: false, children: _jsx("ul", { className: "kpt-autocomplete__panel", role: "listbox", id: listId, "aria-label": rest['aria-label'], children: filtered.map((option, index) => (_jsx("li", { id: optionId(index), className: cn('kpt-autocomplete__option', index === activeIndex && 'is-active'), role: "option", "aria-selected": index === activeIndex, 
                         // `mousedown` z zablokowanym domyślnym zachowaniem: klik w opcję nie może
                         // zabrać fokusu polu, bo `blur` zamknąłby panel przed wyborem.
                         onMouseDown: (event) => {

package/dist/autocomplete/llms.txt

@@ -12,14 +12,14 @@ A text field with suggestions. Import: `import { KptAutocomplete } from '@konce-
     </ul>
 
 ## Props
-- `options`: string[] — the suggestions
-- `value` / `defaultValue` / `onValueChange` — the typed text
+- `options`: string[] - the suggestions
+- `value` / `defaultValue` / `onValueChange` - the typed text
 - `invalid`, `touched`, `onTouch()`
 - `className`, `ref` and every other `<input>` prop go to the input
 
 ## The value is the text, not the option
 Whatever is typed becomes the value; the suggestions only shorten the typing. That makes the field
-usable for values outside the list — a city nobody put in `options` still submits. When the value
+usable for values outside the list - a city nobody put in `options` still submits. When the value
 must come from the list, reach for `KptSelect` instead.
 
 ## No backdrop
@@ -33,13 +33,13 @@ ArrowDown opens the list and moves the active option, ArrowUp moves back, Enter
 one, Escape closes.
 
 ## Examples
-    <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="City…" />
+    <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="City..." />
 
 ## Screen reader and keyboard
 The WAI-ARIA combobox-with-list pattern: focus stays in the field, `aria-autocomplete="list"`,
 `aria-controls` and `aria-activedescendant` point at the active suggestion, and a polite live region
 says how many suggestions there are (`autocomplete.results`) or that there are none
-(`autocomplete.noResults`). Matching ignores case and diacritics ("lodz" finds "Łódź"). `↑` from the
+(`autocomplete.noResults`). Matching ignores case and diacritics ("lodz" finds "Łódź"). `ArrowUp` from the
 field goes to the last suggestion; the first `Escape` closes the list, the second clears the field.
 
 ## Label and description
@@ -54,3 +54,17 @@ added to `aria-describedby` (merged with your own). Without a wrapper, name it w
 ## Accessibility
 The input is `role="combobox"` with `aria-expanded`; the panel is `role="listbox"` with
 `role="option"` rows carrying `aria-selected`.
+
+## Read-only and required
+`readOnly` is the native read-only field with `aria-readonly`; the suggestions do not open and Escape does not clear the value.
+
+## Dictation
+- `speech`: boolean = false - a microphone at the end of the field (`KptSpeechButton`). Hidden without
+  browser support.
+- `speechLang`: string - BCP 47 tag; without it from `KptI18nProvider`.
+- `speechColor`: `'primary' | 'danger' | 'success' | 'warning' | 'info'` = `'primary'` - colour of "stop" and the wave while listening.
+- `speechMode`: `'insert' | 'append' | 'replace'` = `'replace'` - the field picks one value, so a click
+  clears it and one utterance replaces it; the suggestion list opens for the spoken text like for typed
+  text. Interim words are visible but do not filter the list - only final text reaches the state.
+
+    <KptAutocomplete options={cities} value={city} onValueChange={setCity} speech />

package/dist/avatar/avatar.d.ts

@@ -5,7 +5,7 @@ export type KptAvatarShape = 'circle' | 'square';
 export interface KptAvatarProps extends Omit<ComponentPropsWithRef<'span'>, 'children'> {
     /** Adres obrazu; ma pierwszeństwo przed inicjałami i ikoną. */
     src?: string | null;
-    /** Imię i nazwisko — źródło inicjałów, `title` oraz etykiety dostępności. */
+    /** Imię i nazwisko - źródło inicjałów, `title` oraz etykiety dostępności. */
     name?: string;
     /** Nazwa ikony z rejestru, gdy nie ma obrazu ani nazwy. */
     icon?: string | null;
@@ -15,17 +15,17 @@ export interface KptAvatarProps extends Omit<ComponentPropsWithRef<'span'>, 'chi
     decorative?: boolean;
     /**
      * Propsy wrappera hosta (`.kpt-avatar-host`). To on jest elementem układu, więc klasy
-     * pozycjonujące awatar w rodzicu — jak `kpt-card__avatar` — idą właśnie tutaj.
+     * pozycjonujące awatar w rodzicu - jak `kpt-card__avatar` - idą właśnie tutaj.
      */
     hostProps?: KptHostProps<'span'>;
 }
 /**
- * Awatar — obraz, inicjały (z `name`) lub ikona.
+ * Awatar - obraz, inicjały (z `name`) lub ikona.
  *
- * `name` trafia do natywnego `title` (podpowiedź spod kursora — inicjały same w sobie nie mówią,
+ * `name` trafia do natywnego `title` (podpowiedź spod kursora - inicjały same w sobie nie mówią,
  * kto to jest). Bez `src` awatar dostaje dodatkowo `role="img"` i `aria-label`, a same inicjały
- * są `aria-hidden`, żeby czytnik nie przeczytał „AK" litera po literze. Przy `src` etykietę
- * niesie już `alt` obrazu — nie dublujemy jej.
+ * są `aria-hidden`, żeby czytnik nie przeczytał "AK" litera po literze. Przy `src` etykietę
+ * niesie już `alt` obrazu - nie dublujemy jej.
  *
  * @example
  * <KptAvatar src="/u/anna.jpg" />

package/dist/avatar/avatar.js

@@ -1,14 +1,15 @@
+'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { KptIcon } from "../icon/icon.js";
 /**
- * Awatar — obraz, inicjały (z `name`) lub ikona.
+ * Awatar - obraz, inicjały (z `name`) lub ikona.
  *
- * `name` trafia do natywnego `title` (podpowiedź spod kursora — inicjały same w sobie nie mówią,
+ * `name` trafia do natywnego `title` (podpowiedź spod kursora - inicjały same w sobie nie mówią,
  * kto to jest). Bez `src` awatar dostaje dodatkowo `role="img"` i `aria-label`, a same inicjały
- * są `aria-hidden`, żeby czytnik nie przeczytał „AK" litera po literze. Przy `src` etykietę
- * niesie już `alt` obrazu — nie dublujemy jej.
+ * są `aria-hidden`, żeby czytnik nie przeczytał "AK" litera po literze. Przy `src` etykietę
+ * niesie już `alt` obrazu - nie dublujemy jej.
  *
  * @example
  * <KptAvatar src="/u/anna.jpg" />
@@ -17,7 +18,7 @@ import { KptIcon } from "../icon/icon.js";
  */
 export function KptAvatar({ src = null, name = '', icon = null, size = 'md', shape = 'circle', decorative = false, hostProps, className, ...rest }) {
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
-    // Zdjęcie, które się nie wczytało — awatar wraca wtedy do inicjałów (albo ikony). Pamiętamy,
+    // Zdjęcie, które się nie wczytało - awatar wraca wtedy do inicjałów (albo ikony). Pamiętamy,
     // którego `src` dotyczy błąd, więc nowy adres próbuje się wczytać od nowa.
     const [brokenSrc, setBrokenSrc] = useState(null);
     const showImage = !!src && brokenSrc !== src;

package/dist/avatar/llms.txt

@@ -1,32 +1,32 @@
 # KptAvatar (@konce-pt/react)
 
-An avatar — a photo, initials (from `name`) or an icon.
+An avatar - a photo, initials (from `name`) or an icon.
 Import: `import { KptAvatar } from '@konce-pt/react';`
 
 ## DOM
     <span class="kpt-avatar-host">
       <span class="kpt-avatar" data-size="md" data-shape="circle" title="Anna Kowalska">
-        <img class="kpt-avatar__img" src="…" alt="Anna Kowalska">
+        <img class="kpt-avatar__img" src="..." alt="Anna Kowalska">
       </span>
     </span>
 
 ## Props
-- `src`: string | null — a photo; it wins over initials and the icon
-- `name`: string — the source of the initials, the `title` and the accessible label
-- `icon`: string | null — a registry icon name, used when there is neither photo nor name
+- `src`: string | null - a photo; it wins over initials and the icon
+- `name`: string - the source of the initials, the `title` and the accessible label
+- `icon`: string | null - a registry icon name, used when there is neither photo nor name
 - `size`: 'sm' | 'md' | 'lg' | 'xl' (default 'md')
 - `shape`: 'circle' | 'square' (default 'circle')
-- `decorative`: boolean — hides the avatar from screen readers (the name is written next to it)
-- `hostProps` — props for the `.kpt-avatar-host` wrapper
+- `decorative`: boolean - hides the avatar from screen readers (the name is written next to it)
+- `hostProps` - props for the `.kpt-avatar-host` wrapper
 - `className`, `ref` and every other `<span>` prop go to the inner `.kpt-avatar`
 
 ## Fallback order
-`src` → `name` (up to two initials, uppercased) → `icon`. A photo that fails to load drops to the
+`src` -> `name` (up to two initials, uppercased) -> `icon`. A photo that fails to load drops to the
 next step by itself, and a new `src` is tried again. With none of them the avatar renders as an
 empty shape, which is a valid placeholder.
 
 ## Positioning inside a parent
-The host is the layout element, so classes that place the avatar in its parent go to `hostProps` —
+The host is the layout element, so classes that place the avatar in its parent go to `hostProps` -
 the overlapping avatar on a card is `hostProps={{ className: 'kpt-card__avatar' }}`.
 
 ## Examples
@@ -42,5 +42,5 @@ the overlapping avatar on a card is `hostProps={{ className: 'kpt-card__avatar'
 `name` goes into the native `title` (initials alone say nothing). With a photo the name is the
 image's `alt`; without one the avatar is `role="img"` with `aria-label`, and the initials are
 `aria-hidden`. A photo that fails to load falls back to the initials (or the icon); a new `src` is
-tried again. `decorative` removes the avatar from the accessibility tree — use it when the name is
+tried again. `decorative` removes the avatar from the accessibility tree - use it when the name is
 already written next to it.

package/dist/avatar-group/avatar-group.d.ts

@@ -8,15 +8,15 @@ export interface KptAvatarItem {
 }
 export interface KptAvatarGroupProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
     avatars?: readonly KptAvatarItem[];
-    /** Ile awatarów pokazać, zanim pojawi się „+N". */
+    /** Ile awatarów pokazać, zanim pojawi się "+N". */
     max?: number;
     size?: KptAvatarSize;
-    /** Nazwa grupy dla czytników ekranu, np. „Członkowie projektu”; bez niej grupa nie ma roli. */
+    /** Nazwa grupy dla czytników ekranu, np. "Członkowie projektu"; bez niej grupa nie ma roli. */
     label?: string;
 }
 /**
- * Grupa nakładających się awatarów z licznikiem „+N". Buduje na `KptAvatar`, więc każdy element
- * dziedziczy jego `title` z imieniem — inicjały same w sobie nie mówią, kto to jest.
+ * Grupa nakładających się awatarów z licznikiem "+N". Buduje na `KptAvatar`, więc każdy element
+ * dziedziczy jego `title` z imieniem - inicjały same w sobie nie mówią, kto to jest.
  *
  * @example
  * <KptAvatarGroup avatars={team} max={4} />

package/dist/avatar-group/avatar-group.js

@@ -1,10 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../internal/cn.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptAvatar } from "../avatar/avatar.js";
 /**
- * Grupa nakładających się awatarów z licznikiem „+N". Buduje na `KptAvatar`, więc każdy element
- * dziedziczy jego `title` z imieniem — inicjały same w sobie nie mówią, kto to jest.
+ * Grupa nakładających się awatarów z licznikiem "+N". Buduje na `KptAvatar`, więc każdy element
+ * dziedziczy jego `title` z imieniem - inicjały same w sobie nie mówią, kto to jest.
  *
  * @example
  * <KptAvatarGroup avatars={team} max={4} />
@@ -13,7 +14,7 @@ export function KptAvatarGroup({ avatars = [], max = 4, size = 'md', label = '',
     const { t } = useKptMessages({ locale, dictionary });
     const shown = avatars.slice(0, max);
     const overflow = Math.max(0, avatars.length - max);
-    // Sam „+2” nic czytnikowi nie mówi — licznik ma nazwę „i 2 więcej” i podpowiedź z imionami.
+    // Sam "+2" nic czytnikowi nie mówi - licznik ma nazwę "i 2 więcej" i podpowiedź z imionami.
     const hiddenNames = avatars
         .slice(max)
         .map((avatar) => avatar.name)

package/dist/avatar-group/llms.txt

@@ -6,22 +6,22 @@ Import: `import { KptAvatarGroup } from '@konce-pt/react';`
 ## DOM
     <div class="kpt-avatar-group-host">
       <div class="kpt-avatar-group" data-size="lg" role="group" aria-label="Project members">
-        <span class="kpt-avatar-group__item">…KptAvatar…</span>…
+        <span class="kpt-avatar-group__item">...KptAvatar...</span>...
         <span class="kpt-avatar-group__item kpt-avatar-group__more" role="img" data-size="lg"
               aria-label="2 more" title="Marta, Tomasz"><span aria-hidden="true">+2</span></span>
       </div>
     </div>
 
 ## Props
-- `avatars`: `KptAvatarItem[]` — `{ name?, src?, icon? }`
-- `max`: number (default 4) — how many to show before "+N"
+- `avatars`: `KptAvatarItem[]` - `{ name?, src?, icon? }`
+- `max`: number (default 4) - how many to show before "+N"
 - `size`: `'sm' | 'md' | 'lg' | 'xl'`
-- `label`: string — the group's name; with it the row is `role="group"`
+- `label`: string - the group's name; with it the row is `role="group"`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## One list, three fallbacks
-Each entry falls back in order: `src` (a photo) → `name` (initials) → `icon`. A team where only
-some people have a photo therefore needs no branching at the call site — which is exactly the
+Each entry falls back in order: `src` (a photo) -> `name` (initials) -> `icon`. A team where only
+some people have a photo therefore needs no branching at the call site - which is exactly the
 common case.
 
 ## The name survives the overlap
@@ -36,6 +36,6 @@ Every avatar keeps the `title` from `KptAvatar`, so hovering tells you who it is
 The overlap ring uses `--kpt-color-surface`, the "+N" chip `--kpt-color-muted`.
 
 ## Accessibility
-Every avatar keeps its own name. With `label` the row is `role="group"` with that name. The “+N”
-counter is `role="img"` named from `avatarGroup.more` (`{count}` — “2 more”), with the hidden names
+Every avatar keeps its own name. With `label` the row is `role="group"` with that name. The "+N"
+counter is `role="img"` named from `avatarGroup.more` (`{count}` - "2 more"), with the hidden names
 in its `title`. The overlap uses `margin-inline-start`, so it mirrors in RTL.

package/dist/backdrop/backdrop.d.ts

@@ -8,22 +8,22 @@ export interface KptBackdropProps extends ComponentPropsWithRef<'div'> {
     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. */
+    /** 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
+     * 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
+     * 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.
+     * `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`.
      */
@@ -34,14 +34,14 @@ export interface KptBackdropProps extends ComponentPropsWithRef<'div'> {
     cell?: number;
     /** `signal-grid`: odstęp między kwadratami (px). */
     gap?: number;
-    /** `signal-grid`: udział zapalonych komórek przy kotwicy, 0–1. */
+    /** `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.
+     * `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
+     * 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
@@ -57,23 +57,4 @@ export interface KptBackdropProps extends ComponentPropsWithRef<'div'> {
     /** 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

@@ -1,5 +1,6 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } 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";
@@ -10,11 +11,11 @@ const EMPTY = [];
  * 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,
+ * 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 —
+ * Rysowanie i cała matematyka siedzą w `@konce-pt/backdrop`, wspólnym z portem Angulara -
  * ten komponent to sam cykl życia.
  *
  * @example
@@ -23,29 +24,39 @@ const EMPTY = [];
  *   <KptButton>Get started</KptButton>
  * </KptBackdrop>
  */
+const REDUCED_MOTION = '(prefers-reduced-motion: reduce)';
+/** `prefers-reduced-motion` jako zewnętrzny magazyn - bez `setState` w efekcie i bez mignięcia ruchu. */
+function subscribeReducedMotion(onChange) {
+    if (typeof matchMedia === 'undefined')
+        return () => undefined;
+    const query = matchMedia(REDUCED_MOTION);
+    query.addEventListener('change', onChange);
+    return () => query.removeEventListener('change', onChange);
+}
+function readReducedMotion() {
+    return typeof matchMedia !== 'undefined' && matchMedia(REDUCED_MOTION).matches;
+}
 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. */
+    /** 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. */
+    /** 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. */
+    /** 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`. */
+    /** 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"
+     * 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);
+    const reduced = useSyncExternalStore(subscribeReducedMotion, readReducedMotion, () => false);
     /** Licznik zmian motywu; podbicie każe przeliczyć kolory z tokenów na nowo. */
     const [theme, setTheme] = useState(0);
     const paint = useCallback(() => {
@@ -70,10 +81,10 @@ export function KptBackdrop({ effect = 'signal-grid', background = '', speed = 1
     // 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".
+    // 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.
+        // 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;
@@ -82,10 +93,10 @@ export function KptBackdrop({ effect = 'signal-grid', background = '', speed = 1
         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.
+        // 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.
+        // konsolę tym samym zdaniem - zgłaszamy dopiero zestaw inny niż poprzednio.
         const rejected = resolved.invalid.join(', ');
         if (rejected !== reported.current) {
             reported.current = rejected;
@@ -115,7 +126,7 @@ export function KptBackdrop({ effect = 'signal-grid', background = '', speed = 1
             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ę.
+    // Sam rozmiar nie zmienia ustawień, więc renderer zostaje - przelicza tylko geometrię.
     useEffect(() => {
         const element = canvas.current;
         if (!element)
@@ -146,14 +157,7 @@ export function KptBackdrop({ effect = 'signal-grid', background = '', speed = 1
             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ć
+    // 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(() => {
@@ -164,7 +168,7 @@ export function KptBackdrop({ effect = 'signal-grid', background = '', speed = 1
             const scope = canvas.current;
             if (!scope)
                 return;
-            // Ten sam rachunek co w efekcie budującym — inaczej strażnik porównywałby wartość sprzed
+            // 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)
@@ -180,8 +184,9 @@ export function KptBackdrop({ effect = 'signal-grid', background = '', speed = 1
         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;
+            // Prędkość wchodzi w zegar, nie w fazę - suwak przyspiesza obraz zamiast go przeskakiwać. Pętla
+            // restartuje się przy zmianie `speed` (zależność efektu), a zegar żyje w refie, więc nic nie skacze.
+            clock.current += (step / 1000) * speed;
             paint();
             frame = requestAnimationFrame(tick);
         };