@konce-pt/react 0.11.2 → 0.14.0

package/dist/internal/password-strength.js

@@ -0,0 +1,74 @@
+/*
+ * Ocena siły hasła dla miernika `kpt-password`. Bliźniak w porcie Angulara (`shared/password-strength.ts`) - zmiana w obu.
+ *
+ * Wynik idzie przede wszystkim za długością, a nie za regułami składu, które odradza NIST SP 800-63B:
+ * `Password1!` spełnia wszystkie "wielka, cyfra, znak specjalny", a jest jednym z najczęściej
+ * zgadywanych haseł, podczas gdy trzydzieści małych liter jest bardzo mocne. Liczymy przybliżoną
+ * entropię znak po znaku - z puli klas, które naprawdę wystąpiły - i obcinamy ją za powtórzenia,
+ * ciągi (`abcd`, `1234`, `qwerty`) i schemat "Słowo + cyfry + znak". Litery spoza ASCII
+ * (`ą`, `ż`) są literami, nie znakami specjalnymi. Bez słownika: to podpowiedź, nie zabezpieczenie.
+ */
+const KEYBOARD_ROWS = ['qwertyuiop', 'asdfghjkl', 'zxcvbnm', '1234567890'];
+/** Pula znaków z klas, które wystąpiły w haśle. */
+function poolSize(value) {
+    let pool = 0;
+    if (/\p{Ll}/u.test(value))
+        pool += 26;
+    if (/\p{Lu}/u.test(value))
+        pool += 26;
+    if (/\p{N}/u.test(value))
+        pool += 10;
+    if (/[^\P{L}\p{Ll}\p{Lu}]/u.test(value))
+        pool += 40; // litery bez wielkości (np. CJK)
+    if (/[^\p{L}\p{N}]/u.test(value))
+        pool += 33;
+    return Math.max(pool, 10);
+}
+/** Czy `b` stoi zaraz po `a` w alfabecie, cyfrach albo rzędzie klawiatury (w dowolną stronę). */
+function isSequential(a, b) {
+    const diff = Math.abs(b.codePointAt(0) - a.codePointAt(0));
+    if (diff === 1 && /[\p{L}\p{N}]/u.test(a + b))
+        return true;
+    const pair = (a + b).toLowerCase();
+    const reversed = (b + a).toLowerCase();
+    return KEYBOARD_ROWS.some((row) => row.includes(pair) || row.includes(reversed));
+}
+/** Przybliżona entropia w bitach. */
+export function kptPasswordBits(value) {
+    if (!value)
+        return 0;
+    // "Słowo + cyfry + znak" (`Password1!`, `Kwiatek2024`) to pierwsze, co zgaduje atakujący -
+    // liczymy je jak samo słowo pisane małymi literami.
+    const pattern = /^(\p{Lu}?\p{Ll}+)(\p{N}{0,4})([^\p{L}\p{N}]{0,2})$/u.exec(value);
+    const chars = [...(pattern ? pattern[1] : value)];
+    const perChar = Math.log2(pattern ? 26 : poolSize(value));
+    let bits = 0;
+    for (let i = 0; i < chars.length; i += 1) {
+        const prev = chars[i - 1];
+        if (prev === undefined)
+            bits += perChar;
+        else if (chars[i] === prev)
+            bits += 0.5; // aaaa
+        else if (isSequential(prev, chars[i]))
+            bits += 1; // abcd, 1234, qwerty
+        else
+            bits += perChar;
+    }
+    // Doklejone cyfry i znak w schemacie to kilka bitów, nie pełna pula.
+    if (pattern)
+        bits += pattern[2].length * 2 + pattern[3].length * 3;
+    return bits;
+}
+/** Wynik 0-4 z entropii: <28 bardzo słabe, <36 słabe, <50 średnie, <64 dobre, reszta silne. */
+export function kptPasswordScore(value) {
+    const bits = kptPasswordBits(value);
+    if (bits < 28)
+        return 0;
+    if (bits < 36)
+        return 1;
+    if (bits < 50)
+        return 2;
+    if (bits < 64)
+        return 3;
+    return 4;
+}

package/dist/internal/roving.d.ts

@@ -1,9 +1,9 @@
 /**
  * Indeks elementu, na który ma przejść fokus po klawiszu `key`. `disabled[i]` mówi, czy element
- * `i` jest wyłączony — takie są pomijane. Strzałki zawijają się na końcach, `Home`/`End` idą do
+ * `i` jest wyłączony - takie są pomijane. Strzałki zawijają się na końcach, `Home`/`End` idą do
  * pierwszego/ostatniego aktywnego. Zwraca `null` dla klawisza, który nie nawiguje, albo gdy nie ma
  * dokąd przejść.
  */
 export declare function nextRovingIndex(disabled: readonly boolean[], current: number, key: string): number | null;
-/** Pierwszy aktywny indeks od `preferred` — przystanek Tab, gdy wskazany element jest wyłączony. */
+/** Pierwszy aktywny indeks od `preferred` - przystanek Tab, gdy wskazany element jest wyłączony. */
 export declare function rovingStop(disabled: readonly boolean[], preferred: number): number;

package/dist/internal/roving.js

@@ -1,11 +1,11 @@
 /*
- * Nawigacja strzałkami po poziomym rzędzie z jednym przystankiem Tab („roving tabindex”) —
+ * Nawigacja strzałkami po poziomym rzędzie z jednym przystankiem Tab ("roving tabindex") -
  * wspólna dla `KptTabs`, `KptMenubar` i `KptMegamenu`. Port Angulara ma bliźniaczy plik
  * `shared/roving.ts`.
  */
 /**
  * Indeks elementu, na który ma przejść fokus po klawiszu `key`. `disabled[i]` mówi, czy element
- * `i` jest wyłączony — takie są pomijane. Strzałki zawijają się na końcach, `Home`/`End` idą do
+ * `i` jest wyłączony - takie są pomijane. Strzałki zawijają się na końcach, `Home`/`End` idą do
  * pierwszego/ostatniego aktywnego. Zwraca `null` dla klawisza, który nie nawiguje, albo gdy nie ma
  * dokąd przejść.
  */
@@ -34,7 +34,7 @@ export function nextRovingIndex(disabled, current, key) {
             return null;
     }
 }
-/** Pierwszy aktywny indeks od `preferred` — przystanek Tab, gdy wskazany element jest wyłączony. */
+/** Pierwszy aktywny indeks od `preferred` - przystanek Tab, gdy wskazany element jest wyłączony. */
 export function rovingStop(disabled, preferred) {
     if (preferred >= 0 && preferred < disabled.length && !disabled[preferred])
         return preferred;

package/dist/internal/scroll-lock.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Blokuje przewijanie dokumentu i zwraca funkcję zdejmującą tę jedną blokadę. Licznik pozwala
+ * zagnieżdżać okna (szuflada -> dialog): przewijanie wraca dopiero po zdjęciu ostatniej.
+ * `scrollbar-gutter: stable` trzyma miejsce po pasku przewijania, więc treść nie przeskakuje w bok.
+ */
+export declare function kptLockScroll(): () => void;

package/dist/internal/scroll-lock.js

@@ -0,0 +1,35 @@
+/*
+ * Blokada przewijania strony pod oknem modalnym. `showModal()` blokuje interakcję z tłem, ale nie
+ * jego przewijanie - kółko myszy dalej przesuwa stronę. Bliźniak w porcie Angulara (`shared/scroll-lock.ts`) - zmiana w obu.
+ */
+let locks = 0;
+let savedOverflow = '';
+let savedGutter = '';
+/**
+ * Blokuje przewijanie dokumentu i zwraca funkcję zdejmującą tę jedną blokadę. Licznik pozwala
+ * zagnieżdżać okna (szuflada -> dialog): przewijanie wraca dopiero po zdjęciu ostatniej.
+ * `scrollbar-gutter: stable` trzyma miejsce po pasku przewijania, więc treść nie przeskakuje w bok.
+ */
+export function kptLockScroll() {
+    if (typeof document === 'undefined')
+        return () => undefined;
+    const root = document.documentElement;
+    if (locks === 0) {
+        savedOverflow = root.style.overflow;
+        savedGutter = root.style.scrollbarGutter;
+        root.style.overflow = 'hidden';
+        root.style.scrollbarGutter = 'stable';
+    }
+    locks += 1;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        locks -= 1;
+        if (locks === 0) {
+            root.style.overflow = savedOverflow;
+            root.style.scrollbarGutter = savedGutter;
+        }
+    };
+}

package/dist/internal/slot-children.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+/**
+ * Dzieci komponentu ze slotami, z rozwiniętymi fragmentami. `Children.forEach` traktuje
+ * `<>...</>` jak jedno dziecko, więc slot owinięty we fragment (np. z warunku
+ * `{admin && <><KptTab .../><KptTab .../></>}`) był dla komponentu niewidoczny. Rozwijamy fragmenty
+ * rekurencyjnie; `null`, `false` i puste napisy odpadają tak jak w `Children.forEach`.
+ */
+export declare function slotChildren(children: ReactNode): ReactNode[];
+/**
+ * Ostrzeżenie deweloperskie o dziecku, które komponent przyjmujący wyłącznie sloty pominie.
+ * Białe znaki między tagami (`"\n  "`) nie są pomyłką - te przemilczamy.
+ */
+export declare function warnUnslottedChild(component: string, child: ReactNode, expected: string): void;

package/dist/internal/slot-children.js

@@ -0,0 +1,31 @@
+import { Children, Fragment, isValidElement } from 'react';
+import { isDevBuild } from "./dev.js";
+/**
+ * Dzieci komponentu ze slotami, z rozwiniętymi fragmentami. `Children.forEach` traktuje
+ * `<>...</>` jak jedno dziecko, więc slot owinięty we fragment (np. z warunku
+ * `{admin && <><KptTab .../><KptTab .../></>}`) był dla komponentu niewidoczny. Rozwijamy fragmenty
+ * rekurencyjnie; `null`, `false` i puste napisy odpadają tak jak w `Children.forEach`.
+ */
+export function slotChildren(children) {
+    const out = [];
+    Children.forEach(children, (child) => {
+        if (isValidElement(child) && child.type === Fragment) {
+            out.push(...slotChildren(child.props.children));
+        }
+        else if (child !== null && child !== undefined && typeof child !== 'boolean') {
+            out.push(child);
+        }
+    });
+    return out;
+}
+/**
+ * Ostrzeżenie deweloperskie o dziecku, które komponent przyjmujący wyłącznie sloty pominie.
+ * Białe znaki między tagami (`"\n  "`) nie są pomyłką - te przemilczamy.
+ */
+export function warnUnslottedChild(component, child, expected) {
+    if (!isDevBuild())
+        return;
+    if (typeof child === 'string' && child.trim() === '')
+        return;
+    console.warn(`[${component}] Pominięto dziecko, które nie jest slotem - użyj ${expected}.`, child);
+}

package/dist/internal/slot.d.ts

@@ -3,18 +3,18 @@ type AnyProps = Record<string, unknown>;
 /**
  * Scala propsy slotu z propsami dziecka. Zasady, w kolejności ważności:
  * handlery są komponowane (najpierw dziecka, potem slotu), `className` sklejane,
- * `style` nakładane (dziecko wygrywa), `ref` łączony, reszta — dziecko nadpisuje slot.
+ * `style` nakładane (dziecko wygrywa), `ref` łączony, reszta - dziecko nadpisuje slot.
  */
 export declare function mergeSlotProps(slotProps: AnyProps, childProps: AnyProps): AnyProps;
 /**
  * Renderuje `child` z propsami slotu i podmienioną treścią. Używane przez komponenty,
- * które w trybie `asChild` muszą zachować własne opakowanie treści — na przykład
+ * które w trybie `asChild` muszą zachować własne opakowanie treści - na przykład
  * przycisk owija zawartość w `.kpt-button__content` niezależnie od tego, jakim
  * elementem ostatecznie jest.
  */
 export declare function renderAsChild(child: ReactElement, slotProps: AnyProps, content: ReactNode): ReactElement;
 export interface SlotProps {
-    /** Dokładnie jeden element — to on przejmie propsy slotu. */
+    /** Dokładnie jeden element - to on przejmie propsy slotu. */
     children?: ReactNode;
     [prop: string]: unknown;
 }

package/dist/internal/slot.js

@@ -4,7 +4,7 @@ import { composeRefs } from "./compose-refs.js";
 /**
  * Scala propsy slotu z propsami dziecka. Zasady, w kolejności ważności:
  * handlery są komponowane (najpierw dziecka, potem slotu), `className` sklejane,
- * `style` nakładane (dziecko wygrywa), `ref` łączony, reszta — dziecko nadpisuje slot.
+ * `style` nakładane (dziecko wygrywa), `ref` łączony, reszta - dziecko nadpisuje slot.
  */
 export function mergeSlotProps(slotProps, childProps) {
     const merged = { ...slotProps };
@@ -33,7 +33,7 @@ export function mergeSlotProps(slotProps, childProps) {
 }
 /**
  * Renderuje `child` z propsami slotu i podmienioną treścią. Używane przez komponenty,
- * które w trybie `asChild` muszą zachować własne opakowanie treści — na przykład
+ * które w trybie `asChild` muszą zachować własne opakowanie treści - na przykład
  * przycisk owija zawartość w `.kpt-button__content` niezależnie od tego, jakim
  * elementem ostatecznie jest.
  */

package/dist/internal/step.d.ts

@@ -0,0 +1,12 @@
+/** Miejsca po przecinku w zapisie liczby, także wykładniczym (`0.25` -> 2, `1e-7` -> 7). */
+export declare function kptDecimals(n: number): number;
+/**
+ * Zaokrągla do precyzji, która nie gubi ani kroku, ani wartości bazowej: `0.1 + 0.2` nie może
+ * dać `0.30000000000000004`, a `1.25 + 1` musi dać `2.25`, nie `2`.
+ */
+export declare function kptRoundTo(n: number, ...sources: number[]): number;
+/**
+ * Przyciąga wartość do siatki `min + k,step` i przycina do zakresu. Siatka zaczyna się od `min`,
+ * nie od zera - przy `min=1, step=2` dozwolone są 1, 3, 5..., tak samo myszą jak klawiaturą.
+ */
+export declare function kptSnapToStep(raw: number, min: number, max: number, step: number): number;

package/dist/internal/step.js

@@ -0,0 +1,31 @@
+/*
+ * Arytmetyka kroku kontrolek liczbowych (`kpt-input-number`, `kpt-knob`).
+ * Bliźniak w porcie Angulara (`shared/step.ts`) - zmiana w obu.
+ */
+/** Miejsca po przecinku w zapisie liczby, także wykładniczym (`0.25` -> 2, `1e-7` -> 7). */
+export function kptDecimals(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    const [mantissa, exponent] = String(n).toLowerCase().split('e');
+    return Math.max(0, (mantissa.split('.')[1] ?? '').length - Number(exponent ?? 0));
+}
+/**
+ * Zaokrągla do precyzji, która nie gubi ani kroku, ani wartości bazowej: `0.1 + 0.2` nie może
+ * dać `0.30000000000000004`, a `1.25 + 1` musi dać `2.25`, nie `2`.
+ */
+export function kptRoundTo(n, ...sources) {
+    const decimals = Math.min(20, Math.max(0, ...sources.map(kptDecimals)));
+    return Number(n.toFixed(decimals));
+}
+/**
+ * Przyciąga wartość do siatki `min + k,step` i przycina do zakresu. Siatka zaczyna się od `min`,
+ * nie od zera - przy `min=1, step=2` dozwolone są 1, 3, 5..., tak samo myszą jak klawiaturą.
+ */
+export function kptSnapToStep(raw, min, max, step) {
+    if (!(step > 0))
+        return Math.min(max, Math.max(min, raw));
+    const snapped = kptRoundTo(min + Math.round((raw - min) / step) * step, step, min);
+    if (snapped > max)
+        return kptRoundTo(max - ((max - min) % step), step, min);
+    return Math.max(min, snapped);
+}

package/dist/internal/tween.d.ts

@@ -1,17 +1,17 @@
 /**
- * Płynne dojście liczby do celu — dla kontrolek, które pokazują wartość rysunkiem (łuk pokrętła)
+ * Płynne dojście liczby do celu - dla kontrolek, które pokazują wartość rysunkiem (łuk pokrętła)
  * i licznikiem. Pure TS bez frameworka; bliźniak portu Angulara: `shared/tween.ts`.
  *
  * Bez animacji, gdy użytkownik prosi o ograniczenie ruchu (`prefers-reduced-motion`) albo gdy nie
- * ma `requestAnimationFrame` (render po stronie serwera) — wtedy cel ustawia się od razu.
+ * ma `requestAnimationFrame` (render po stronie serwera) - wtedy cel ustawia się od razu.
  */
-/** Czy animować — reguła wspólna dla wszystkich kontrolek, żeby „mniej ruchu" działało wszędzie. */
+/** Czy animować - reguła wspólna dla wszystkich kontrolek, żeby "mniej ruchu" działało wszędzie. */
 export declare function kptMotionAllowed(): boolean;
 /**
  * Animuje od `from` do `to` przez `duration` ms, wołając `onFrame` z wartością pośrednią.
- * Zwraca funkcję przerwania — kolejny skok przerywa poprzedni i rusza z miejsca, w którym ten był,
+ * Zwraca funkcję przerwania - kolejny skok przerywa poprzedni i rusza z miejsca, w którym ten był,
  * więc szybkie stuknięcia strzałką nie cofają łuku do startu.
  */
 export declare function kptTween(from: number, to: number, duration: number, onFrame: (value: number) => void): () => void;
-/** Liczba miejsc po przecinku kroku (`0.25` → 2) — licznik w trakcie animacji nie pokazuje szumu. */
+/** Liczba miejsc po przecinku kroku (`0.25` -> 2) - licznik w trakcie animacji nie pokazuje szumu. */
 export declare function kptStepDecimals(step: number): number;

package/dist/internal/tween.js

@@ -1,13 +1,14 @@
 /**
- * Płynne dojście liczby do celu — dla kontrolek, które pokazują wartość rysunkiem (łuk pokrętła)
+ * Płynne dojście liczby do celu - dla kontrolek, które pokazują wartość rysunkiem (łuk pokrętła)
  * i licznikiem. Pure TS bez frameworka; bliźniak portu Angulara: `shared/tween.ts`.
  *
  * Bez animacji, gdy użytkownik prosi o ograniczenie ruchu (`prefers-reduced-motion`) albo gdy nie
- * ma `requestAnimationFrame` (render po stronie serwera) — wtedy cel ustawia się od razu.
+ * ma `requestAnimationFrame` (render po stronie serwera) - wtedy cel ustawia się od razu.
  */
+import { kptDecimals } from "./step.js";
 /** Zwolnienie pod koniec (ease-out cubic): ruch rusza od razu i dojeżdża miękko. */
 const easeOut = (t) => 1 - (1 - t) ** 3;
-/** Czy animować — reguła wspólna dla wszystkich kontrolek, żeby „mniej ruchu" działało wszędzie. */
+/** Czy animować - reguła wspólna dla wszystkich kontrolek, żeby "mniej ruchu" działało wszędzie. */
 export function kptMotionAllowed() {
     if (typeof requestAnimationFrame === 'undefined')
         return false;
@@ -15,7 +16,7 @@ export function kptMotionAllowed() {
 }
 /**
  * Animuje od `from` do `to` przez `duration` ms, wołając `onFrame` z wartością pośrednią.
- * Zwraca funkcję przerwania — kolejny skok przerywa poprzedni i rusza z miejsca, w którym ten był,
+ * Zwraca funkcję przerwania - kolejny skok przerywa poprzedni i rusza z miejsca, w którym ten był,
  * więc szybkie stuknięcia strzałką nie cofają łuku do startu.
  */
 export function kptTween(from, to, duration, onFrame) {
@@ -32,9 +33,7 @@ export function kptTween(from, to, duration, onFrame) {
     });
     return () => cancelAnimationFrame(frame);
 }
-/** Liczba miejsc po przecinku kroku (`0.25` → 2) — licznik w trakcie animacji nie pokazuje szumu. */
+/** Liczba miejsc po przecinku kroku (`0.25` -> 2) - licznik w trakcie animacji nie pokazuje szumu. */
 export function kptStepDecimals(step) {
-    const text = String(step);
-    const dot = text.indexOf('.');
-    return dot === -1 ? 0 : text.length - dot - 1;
+    return kptDecimals(step);
 }

package/dist/internal/types.d.ts

@@ -3,12 +3,12 @@ import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
  * Propsy wrappera hosta. Port odtwarza dwupoziomowy DOM Angulara
  * (`<kpt-button class="kpt-button-host">` wokół `<button class="kpt-button">`),
  * bo host niesie własne style. `className` i `ref` komponentu trafiają na element
- * wewnętrzny — wrapper konfiguruje się właśnie tym propem.
+ * wewnętrzny - wrapper konfiguruje się właśnie tym propem.
  */
 export type KptHostProps<E extends ElementType = 'span'> = Omit<ComponentPropsWithoutRef<E>, 'children'> & {
     /**
      * Atrybuty `data-*` hosta. JSX przepuszcza je na elementach wbudowanych sam z siebie,
-     * ale ten typ opisuje zwykły obiekt — bez tego wpisu stan wariantu, który w Angularze
+     * ale ten typ opisuje zwykły obiekt - bez tego wpisu stan wariantu, który w Angularze
      * siedzi na hoście (`[attr.data-on]`), nie miałby jak tam trafić.
      */
     [key: `data-${string}`]: string | number | boolean | undefined;

package/dist/internal/use-breakpoint.d.ts

@@ -1,7 +1,7 @@
 /** Nazwa breakpointa z tokenów `--kpt-breakpoint-*` (mobile-first). */
 export type KptBreakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 /**
- * Progi breakpointów w pikselach — czytane wprost z `@konce-pt/tokens`, więc nie da się
+ * Progi breakpointów w pikselach - czytane wprost z `@konce-pt/tokens`, więc nie da się
  * ich rozjechać z `@media` biblioteki ani z portem Angulara (tam ta sama tabela powstaje
  * w kroku generowania).
  */
@@ -11,7 +11,7 @@ export declare function useKptMediaQuery(query: string): boolean;
 /**
  * Czy viewport ma szerokość co najmniej danego breakpointa (mobile-first).
  *
- * O UKŁADZIE komponentów decyduje wyłącznie CSS — ten hook odpowiada tylko za zachowania,
+ * O UKŁADZIE komponentów decyduje wyłącznie CSS - ten hook odpowiada tylko za zachowania,
  * których CSS nie wyrazi (np. w którą stronę ma zadziałać przycisk). Dzięki temu nic nie
  * migocze przed hydracją.
  */

package/dist/internal/use-breakpoint.js

@@ -2,7 +2,7 @@ import { useSyncExternalStore } from 'react';
 import { KPT_BREAKPOINT_2XL, KPT_BREAKPOINT_LG, KPT_BREAKPOINT_MD, KPT_BREAKPOINT_SM, KPT_BREAKPOINT_XL, } from '@konce-pt/tokens';
 const toPx = (value) => Number.parseFloat(value);
 /**
- * Progi breakpointów w pikselach — czytane wprost z `@konce-pt/tokens`, więc nie da się
+ * Progi breakpointów w pikselach - czytane wprost z `@konce-pt/tokens`, więc nie da się
  * ich rozjechać z `@media` biblioteki ani z portem Angulara (tam ta sama tabela powstaje
  * w kroku generowania).
  */
@@ -15,7 +15,7 @@ export const KPT_BREAKPOINTS = {
 };
 /**
  * Jeden `MediaQueryList` i jeden nasłuch na zapytanie, współdzielone przez wszystkie
- * komponenty — tak samo jak memoizacja w `KptBreakpointObserver` po stronie Angulara.
+ * komponenty - tak samo jak memoizacja w `KptBreakpointObserver` po stronie Angulara.
  */
 const stores = new Map();
 /**
@@ -27,7 +27,7 @@ function storeFor(query) {
     const cached = stores.get(query);
     if (cached)
         return cached;
-    // Sam brak `window` nie wystarcza: jsdom go dostarcza, ale bez `matchMedia` — bez sprawdzenia
+    // Sam brak `window` nie wystarcza: jsdom go dostarcza, ale bez `matchMedia` - bez sprawdzenia
     // metody każdy test dotykający `KptAppShell` wywala się na TypeError. Wyniku nie zapisujemy
     // w cache'u, żeby stub podstawiony później (typowy `setup` testów) został podchwycony.
     if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
@@ -51,7 +51,7 @@ export function useKptMediaQuery(query) {
 /**
  * Czy viewport ma szerokość co najmniej danego breakpointa (mobile-first).
  *
- * O UKŁADZIE komponentów decyduje wyłącznie CSS — ten hook odpowiada tylko za zachowania,
+ * O UKŁADZIE komponentów decyduje wyłącznie CSS - ten hook odpowiada tylko za zachowania,
  * których CSS nie wyrazi (np. w którą stronę ma zadziałać przycisk). Dzięki temu nic nie
  * migocze przed hydracją.
  */

package/dist/internal/use-controllable-state.d.ts

@@ -3,6 +3,11 @@
  * i niekontrolowanym (`defaultValue` + stan wewnętrzny). Kontrakt jest ten sam
  * co w natywnych polach formularza, więc komponenty współpracują z natywnym
  * `<form>`, React 19 Actions i React Hook Form bez adapterów.
+ *
+ * `setValue` ma stałą tożsamość: rodzic przekazujący `onChange` jako funkcję inline nie restartuje
+ * efektów, które mają `setValue` w zależnościach. Przejście między trybami (`value` raz podane,
+ * raz `undefined`) działa jak w Reakcie - po cichu przełącza źródło - ale w buildzie deweloperskim
+ * ostrzega, tak jak React robi to dla `<input>`.
  */
 export declare function useControllableState<T>(options: {
     value: T | undefined;

package/dist/internal/use-controllable-state.js

@@ -1,18 +1,39 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { isDevBuild } from "./dev.js";
 /**
  * Stan działający w obu trybach naraz: kontrolowanym (`value` podane z zewnątrz)
  * i niekontrolowanym (`defaultValue` + stan wewnętrzny). Kontrakt jest ten sam
  * co w natywnych polach formularza, więc komponenty współpracują z natywnym
  * `<form>`, React 19 Actions i React Hook Form bez adapterów.
+ *
+ * `setValue` ma stałą tożsamość: rodzic przekazujący `onChange` jako funkcję inline nie restartuje
+ * efektów, które mają `setValue` w zależnościach. Przejście między trybami (`value` raz podane,
+ * raz `undefined`) działa jak w Reakcie - po cichu przełącza źródło - ale w buildzie deweloperskim
+ * ostrzega, tak jak React robi to dla `<input>`.
  */
 export function useControllableState(options) {
     const { value, defaultValue, onChange } = options;
     const isControlled = value !== undefined;
     const [uncontrolled, setUncontrolled] = useState(defaultValue);
+    // Najświeższy tryb i callback dla stabilnego `setValue` - odświeżane po zatwierdzeniu renderu.
+    const latest = useRef({ isControlled, onChange });
+    useLayoutEffect(() => {
+        latest.current = { isControlled, onChange };
+    });
     const setValue = useCallback((next) => {
-        if (!isControlled)
+        if (!latest.current.isControlled)
             setUncontrolled(next);
-        onChange?.(next);
-    }, [isControlled, onChange]);
+        latest.current.onChange?.(next);
+    }, []);
+    const [initiallyControlled] = useState(isControlled);
+    const warned = useRef(false);
+    useEffect(() => {
+        if (warned.current || isControlled === initiallyControlled || !isDevBuild())
+            return;
+        warned.current = true;
+        console.warn(isControlled
+            ? '[koncept-ui] Komponent przeszedł z trybu niekontrolowanego w kontrolowany (`value` było undefined). Wybierz jeden tryb na całe życie komponentu.'
+            : '[koncept-ui] Komponent przeszedł z trybu kontrolowanego w niekontrolowany (`value` stało się undefined). Do "braku wartości" użyj null, nie undefined.');
+    }, [isControlled, initiallyControlled]);
     return [isControlled ? value : uncontrolled, setValue];
 }

package/dist/internal/use-id.d.ts

@@ -1,9 +1,9 @@
 /**
- * Stabilny identyfikator elementu w konwencji Angulara (`kpt-input-…`), z tą samą
+ * Stabilny identyfikator elementu w konwencji Angulara (`kpt-input-...`), z tą samą
  * zasadą pierwszeństwa: własne `id` przekazane przez propsy wygrywa.
  *
  * `useId()` z Reacta zwraca wartość ze znakami spoza [A-Za-z0-9] (React 19 używa
- * `«r0»`), która jest poprawna w atrybucie `id`, ale nie w selektorze CSS —
+ * `"r0"`), która jest poprawna w atrybucie `id`, ale nie w selektorze CSS -
  * dlatego zostawiamy z niej tylko część alfanumeryczną.
  */
 export declare function useKptId(provided: string | undefined, prefix: string): string;

package/dist/internal/use-id.js

@@ -1,10 +1,10 @@
 import { useId } from 'react';
 /**
- * Stabilny identyfikator elementu w konwencji Angulara (`kpt-input-…`), z tą samą
+ * Stabilny identyfikator elementu w konwencji Angulara (`kpt-input-...`), z tą samą
  * zasadą pierwszeństwa: własne `id` przekazane przez propsy wygrywa.
  *
  * `useId()` z Reacta zwraca wartość ze znakami spoza [A-Za-z0-9] (React 19 używa
- * `«r0»`), która jest poprawna w atrybucie `id`, ale nie w selektorze CSS —
+ * `"r0"`), która jest poprawna w atrybucie `id`, ale nie w selektorze CSS -
  * dlatego zostawiamy z niej tylko część alfanumeryczną.
  */
 export function useKptId(provided, prefix) {

package/dist/internal/use-modal-focus.d.ts

@@ -4,7 +4,8 @@ import { type RefObject } from 'react';
  * z fokusem, przenosi fokus do panelu (pierwszy element z kolejki Tab albo sam panel) i zawija
  * `Tab` / `Shift+Tab` w jego obrębie; przy zamknięciu oddaje fokus zapamiętanemu elementowi.
  * Bez tego `aria-modal="true"` obiecywał czytnikowi okno, z którego Tab po cichu wychodził.
+ * Otwarty panel blokuje też przewijanie strony pod spodem (wspólny licznik z `KptDialog`).
  *
- * Port Angulara robi to samo na pułapce CDK (`shared/modal-focus.ts`) — zmiana zachowania w obu.
+ * Port Angulara robi to samo na pułapce CDK (`shared/modal-focus.ts`) - zmiana zachowania w obu.
  */
 export declare function useModalFocus(open: boolean, panelRef: RefObject<HTMLElement | null>): void;

package/dist/internal/use-modal-focus.js

@@ -1,5 +1,11 @@
 import { useEffect } from 'react';
-/** Elementy z kolejki Tab — na nich zawija się pułapka. */
+import { kptLockScroll } from "./scroll-lock.js";
+/**
+ * Stos otwartych paneli modalnych. Pułapki słuchają `keydown` na dokumencie, więc przy dwóch
+ * otwartych naraz (szuflada -> dialog) walczyłyby o ten sam Tab - klawisz obsługuje tylko najwyższa.
+ */
+const stack = [];
+/** Elementy z kolejki Tab - na nich zawija się pułapka. */
 const TABBABLE = 'a[href], button:not(:disabled), input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])';
 function tabbables(panel) {
     return [...panel.querySelectorAll(TABBABLE)].filter((el) => !el.closest('[hidden], [inert]'));
@@ -9,8 +15,9 @@ function tabbables(panel) {
  * z fokusem, przenosi fokus do panelu (pierwszy element z kolejki Tab albo sam panel) i zawija
  * `Tab` / `Shift+Tab` w jego obrębie; przy zamknięciu oddaje fokus zapamiętanemu elementowi.
  * Bez tego `aria-modal="true"` obiecywał czytnikowi okno, z którego Tab po cichu wychodził.
+ * Otwarty panel blokuje też przewijanie strony pod spodem (wspólny licznik z `KptDialog`).
  *
- * Port Angulara robi to samo na pułapce CDK (`shared/modal-focus.ts`) — zmiana zachowania w obu.
+ * Port Angulara robi to samo na pułapce CDK (`shared/modal-focus.ts`) - zmiana zachowania w obu.
  */
 export function useModalFocus(open, panelRef) {
     useEffect(() => {
@@ -19,6 +26,8 @@ export function useModalFocus(open, panelRef) {
             return;
         const active = document.activeElement;
         const returnTo = active instanceof HTMLElement && !panel.contains(active) ? active : null;
+        stack.push(panel);
+        const releaseScroll = kptLockScroll();
         // Klatkę później: panel dostaje `is-open` (i `visibility: visible`) w tym samym commicie,
         // a przeglądarka nie skupi elementu, który w chwili wywołania jest jeszcze niewidoczny.
         const frame = requestAnimationFrame(() => {
@@ -26,7 +35,7 @@ export function useModalFocus(open, panelRef) {
             (first ?? panel).focus();
         });
         const onKeyDown = (event) => {
-            if (event.key !== 'Tab')
+            if (event.key !== 'Tab' || stack[stack.length - 1] !== panel)
                 return;
             const items = tabbables(panel);
             if (!items.length) {
@@ -50,6 +59,8 @@ export function useModalFocus(open, panelRef) {
         return () => {
             cancelAnimationFrame(frame);
             document.removeEventListener('keydown', onKeyDown);
+            stack.splice(stack.indexOf(panel), 1);
+            releaseScroll();
             if (returnTo?.isConnected)
                 returnTo.focus();
         };

package/dist/knob/knob.d.ts

@@ -13,23 +13,26 @@ export interface KptKnobProps extends Omit<ComponentPropsWithRef<'div'>, 'onChan
     /** Dopisek za wartością w środku (np. '%'). */
     suffix?: string;
     showValue?: boolean;
-    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` - z wrappera. */
     id?: string;
     /** Nazwa dostępna, gdy kontrolki nie opisuje etykieta (`<label for>` albo `KptFormField`). */
     ariaLabel?: string | null;
     disabled?: boolean;
+    /** Tylko do odczytu - pokrętło widać i da się na nim stanąć, ale nie zmienić wartości. */
+    readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
     onTouch?: () => void;
 }
 /**
- * Pokrętło — wybór wartości po łuku, przeciąganiem albo strzałkami.
+ * Pokrętło - wybór wartości po łuku, przeciąganiem albo strzałkami.
  *
  * Skok wartości (strzałka, `Home`/`End`, klik w łuk, zmiana z zewnątrz) łuk i licznik pokonują
- * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `prefers-reduced-motion` wyłącza
+ * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `PageUp`/`PageDown` skaczą o dziesięć
+ * kroków, a wartości leżą na siatce `min + k,step` dla myszy i klawiatury. `prefers-reduced-motion` wyłącza
  * animację, a `aria-valuenow` zawsze niesie wartość docelową, nie pośrednią.
  *
  * @example
  * <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
  */
-export declare function KptKnob({ value, defaultValue, onValueChange, min, max, step, size, stroke, suffix, showValue, id, ariaLabel, disabled, invalid, touched, onTouch, className, ...rest }: Readonly<KptKnobProps>): import("react").JSX.Element;
+export declare function KptKnob({ value, defaultValue, onValueChange, min, max, step, size, stroke, suffix, showValue, id, ariaLabel, disabled, readOnly, invalid, touched, onTouch, className, ...rest }: Readonly<KptKnobProps>): import("react").JSX.Element;