@konce-pt/react 0.11.1 → 0.12.0

package/dist/input-otp/input-otp.js

@@ -1,51 +1,73 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptFieldA11y } from "../form-field/form-field-context.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 /**
  * Pole kodu jednorazowego (OTP/PIN) — N osobnych pól, automatyczne przejście do następnego
- * i wklejanie całego kodu naraz. Wartością jest sklejony string.
+ * i wklejanie całego kodu naraz. Wartością są wpisane znaki **bez dziur** (`'13'`, nie `'1 3'`), więc
+ * walidator długości i backend widzą tyle znaków, ile naprawdę wpisano.
  *
  * @example
  * <KptInputOtp value={code} onValueChange={setCode} length={6} integerOnly />
+ * <KptInputOtp value={code} onValueChange={setCode} length={9} groupSize={3} />
  */
-export function KptInputOtp({ value, defaultValue = '', onValueChange, length = 6, integerOnly = false, id, ariaLabel = null, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptInputOtp({ value, defaultValue = '', onValueChange, length = 6, groupSize = 0, groupSeparator = '–', integerOnly = false, id, ariaLabel = null, disabled = false, readOnly = false, required = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const field = useKptFieldA11y(id, 'kpt-input-otp');
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const showInvalid = invalid && (touched ?? true);
-    const charAt = (index) => current[index] ?? '';
     /*
-     * Wartość jest jednym stringiem, a pól jest N — pozycje pośrodku muszą więc dać się zostawić
-     * puste. Dopełniamy spacjami, podmieniamy znak i obcinamy końcowe spacje, żeby „a__c" dało się
-     * zapisać, a „a" nie zamieniło się w „a   ".
+     * Komórki trzymają układ osobno od wartości: wyczyszczenie środkowej zostawia w niej pustkę,
+     * zamiast przesuwać resztę kodu w lewo, a wartość to same znaki. Zmiana wartości z zewnątrz
+     * (inna niż złożenie bieżących komórek) układa znaki od początku — wzorzec „poprzednia
+     * wartość w stanie”, bez efektu.
      */
+    const toCells = (text) => Array.from({ length }, (_, index) => text[index] ?? '');
+    const [cells, setCells] = useState(() => toCells(current));
+    const inSync = cells.length === length && cells.join('') === current;
+    if (!inSync)
+        setCells(toCells(current));
+    const shown = inSync ? cells : toCells(current);
+    const charAt = (index) => shown[index] ?? '';
+    /** Zapis komórek i złożonej z nich wartości — jedno miejsce, żeby układ i model się nie rozjechały. */
+    const commitCells = (next) => {
+        setCells(next);
+        setCurrent(next.join(''));
+    };
     const setChar = (index, char) => {
-        const chars = current.padEnd(length, ' ').split('');
-        chars[index] = char || ' ';
-        setCurrent(chars.join('').replace(/ +$/, ''));
+        const next = [...shown];
+        next[index] = char;
+        commitCells(next);
     };
+    /** Następna/poprzednia komórka — po polach, nie po rodzeństwie, bo między grupami stoi separator. */
     const focusSibling = (el, direction) => {
-        const target = direction === 1 ? el.nextElementSibling : el.previousElementSibling;
-        target?.focus();
+        const cells = [...(el.closest('.kpt-input-otp')?.querySelectorAll('input') ?? [])];
+        cells[cells.indexOf(el) + direction]?.focus();
     };
+    /** Czy za komórką `index` kończy się grupa (a nie cały kod). */
+    const group = Math.floor(groupSize);
+    const separatorAfter = (index) => group >= 1 && (index + 1) % group === 0 && index < length - 1;
     /** Wpisuje `text` od komórki `start` (bez spacji i — przy `integerOnly` — bez nie-cyfr). */
     const fillFrom = (start, text, el) => {
         let chars = text.replace(/\s/g, '');
         if (integerOnly)
             chars = chars.replace(/\D/g, '');
-        const arr = current.padEnd(length, ' ').split('');
+        const arr = [...shown];
         for (let k = 0; k < chars.length && start + k < length; k += 1)
             arr[start + k] = chars[k];
-        setCurrent(arr.join('').replace(/ +$/, ''));
+        commitCells(arr);
         // Fokus na pierwszą pustą komórkę, a przy komplecie — na ostatnią.
-        const cells = [...(el.closest('.kpt-input-otp')?.querySelectorAll('input') ?? [])];
-        const empty = arr.findIndex((char) => char === ' ');
-        cells[empty >= 0 ? empty : cells.length - 1]?.focus();
+        const inputs = [...(el.closest('.kpt-input-otp')?.querySelectorAll('input') ?? [])];
+        const empty = arr.findIndex((char) => char === '');
+        inputs[empty >= 0 ? empty : inputs.length - 1]?.focus();
     };
     const onInput = (index, event) => {
         const el = event.target;
+        if (readOnly)
+            return;
         // Kilka znaków naraz to autouzupełnienie kodu z SMS (`one-time-code`) albo wklejenie przez
         // klawiaturę ekranową — rozkładamy je po komórkach od bieżącej. Dwa znaki w zajętej komórce
         // to zwykłe nadpisanie: stary znak + nowy.
@@ -67,7 +89,7 @@ export function KptInputOtp({ value, defaultValue = '', onValueChange, length =
     };
     const onKeyDown = (index, event) => {
         const el = event.currentTarget;
-        if (event.key === 'Backspace' && !charAt(index))
+        if (event.key === 'Backspace' && !charAt(index) && !readOnly)
             focusSibling(el, -1);
         else if (event.key === 'ArrowLeft')
             focusSibling(el, -1);
@@ -76,6 +98,8 @@ export function KptInputOtp({ value, defaultValue = '', onValueChange, length =
     };
     const onPaste = (event) => {
         event.preventDefault();
+        if (readOnly)
+            return;
         fillFrom(0, event.clipboardData.getData('text'), event.currentTarget);
     };
     /** „Dotknięcie” dopiero przy wyjściu fokusu z całej grupy, nie przy przejściu między komórkami. */
@@ -84,5 +108,5 @@ export function KptInputOtp({ value, defaultValue = '', onValueChange, length =
         if (!next || !event.currentTarget.contains(next))
             onTouch?.();
     };
-    return (_jsx("div", { className: cn('kpt-input-otp-host', className), ...rest, children: _jsx("div", { className: cn('kpt-input-otp', showInvalid && 'kpt-input-otp--invalid'), role: "group", "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onBlur: onGroupBlur, children: Array.from({ length }, (_, index) => (_jsx("input", { className: "kpt-input-otp__cell", id: index === 0 ? field.id : undefined, "aria-label": t('inputOtp.cell', { index: index + 1, count: length }), "aria-invalid": showInvalid || undefined, type: "text", inputMode: integerOnly ? 'numeric' : 'text', autoComplete: index === 0 ? 'one-time-code' : 'off', value: charAt(index), disabled: disabled, onChange: (event) => onInput(index, event), onKeyDown: (event) => onKeyDown(index, event), onPaste: onPaste, onFocus: (event) => event.target.select() }, index))) }) }));
+    return (_jsx("div", { className: cn('kpt-input-otp-host', className), ...rest, children: _jsx("div", { className: cn('kpt-input-otp', showInvalid && 'kpt-input-otp--invalid'), role: "group", "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onBlur: onGroupBlur, children: Array.from({ length }, (_, index) => (_jsxs(Fragment, { children: [_jsx("input", { className: "kpt-input-otp__cell", id: index === 0 ? field.id : undefined, "aria-label": t('inputOtp.cell', { index: index + 1, count: length }), "aria-invalid": showInvalid || undefined, type: "text", inputMode: integerOnly ? 'numeric' : 'text', autoComplete: index === 0 ? 'one-time-code' : 'off', value: charAt(index), disabled: disabled, readOnly: readOnly, "aria-required": required || undefined, onChange: (event) => onInput(index, event), onKeyDown: (event) => onKeyDown(index, event), onPaste: onPaste, onFocus: (event) => event.target.select() }), separatorAfter(index) ? (_jsx("span", { className: "kpt-input-otp__sep", "aria-hidden": "true", children: groupSeparator })) : null] }, index))) }) }));
 }

package/dist/input-otp/llms.txt

@@ -55,3 +55,14 @@ is added to `aria-describedby`. The cells form a named `role="group"`; `id` goes
 ## Accessibility
 Native inputs with `inputmode` matched to the allowed characters, so a phone shows the numeric
 keypad for a PIN instead of the full keyboard.
+
+## Read-only and required
+`readOnly` shows the code but blocks typing and paste; `required` sets `aria-required` on the cells (`group` does not accept it). The value holds the typed characters **without gaps**: clearing a middle cell gives `"13"`, not `"1 3"`, while the cell itself stays empty on screen.
+
+## Groups
+`groupSize` (default `0` = no groups) inserts a separator after every N boxes, counted from the
+left; `groupSeparator` sets the character (default `–`). With `length` 9 and `groupSize` 3 you get
+`[][][]–[][][]–[][][]`. The separator is purely visual (`aria-hidden`): the value is the bare characters
+(`"123456789"`), each box keeps its name "Character 4 of 9", and arrows/Backspace jump over it.
+
+    <KptInputOtp value={code} onValueChange={setCode} length={9} groupSize={3} integerOnly />

package/dist/internal/mask.d.ts

@@ -0,0 +1,14 @@
+/** Tokeny maski: `9` = cyfra, `a` = litera (także `ą`, `ł`, `ß`), `*` = litera albo cyfra. */
+export declare const KPT_MASK_TOKENS: Readonly<Record<string, RegExp>>;
+/**
+ * Maska przepisuje wejście od zera: z tekstu bierze wyłącznie znaki pasujące do kolejnych
+ * tokenów, a literały wstawia sama. Dzięki temu wklejenie „48123456789” i wpisanie „(48) 123…”
+ * dają ten sam wynik, a usunięcie literału nie zostawia dziury we wzorcu.
+ */
+export declare function kptApplyMask(raw: string, mask: string): string;
+/**
+ * Pozycja kursora po przeformatowaniu. Liczy znaczące znaki (te, które maska zabrała) przed
+ * kursorem w surowym tekście i stawia kursor za tyloma samymi znakami w wyniku — poprawienie
+ * cyfry w środku numeru nie przerzuca kursora na koniec pola.
+ */
+export declare function kptMaskCaret(raw: string, caret: number, mask: string): number;

package/dist/internal/mask.js

@@ -0,0 +1,62 @@
+/*
+ * Maska znakowa `kpt-input-mask`. Bliźniak w porcie Angulara (`shared/mask.ts`) — zmiana w obu.
+ */
+/** Tokeny maski: `9` = cyfra, `a` = litera (także `ą`, `ł`, `ß`), `*` = litera albo cyfra. */
+export const KPT_MASK_TOKENS = {
+    '9': /\d/,
+    a: /\p{L}/u,
+    '*': /[\p{L}\p{N}]/u,
+};
+/**
+ * Maska przepisuje wejście od zera: z tekstu bierze wyłącznie znaki pasujące do kolejnych
+ * tokenów, a literały wstawia sama. Dzięki temu wklejenie „48123456789” i wpisanie „(48) 123…”
+ * dają ten sam wynik, a usunięcie literału nie zostawia dziury we wzorcu.
+ */
+export function kptApplyMask(raw, mask) {
+    if (!mask)
+        return raw;
+    const chars = [...raw];
+    let charIndex = 0;
+    let out = '';
+    for (let maskIndex = 0; maskIndex < mask.length && charIndex < chars.length;) {
+        const rule = KPT_MASK_TOKENS[mask[maskIndex]];
+        if (rule) {
+            while (charIndex < chars.length && !rule.test(chars[charIndex]))
+                charIndex++;
+            if (charIndex >= chars.length)
+                break;
+            out += chars[charIndex];
+            charIndex++;
+        }
+        else {
+            out += mask[maskIndex];
+        }
+        maskIndex++;
+    }
+    return out;
+}
+/**
+ * Pozycja kursora po przeformatowaniu. Liczy znaczące znaki (te, które maska zabrała) przed
+ * kursorem w surowym tekście i stawia kursor za tyloma samymi znakami w wyniku — poprawienie
+ * cyfry w środku numeru nie przerzuca kursora na koniec pola.
+ */
+export function kptMaskCaret(raw, caret, mask) {
+    const formatted = kptApplyMask(raw, mask);
+    if (!mask)
+        return Math.min(caret, formatted.length);
+    const before = kptApplyMask(raw.slice(0, caret), mask);
+    // Ile znaczących znaków jest przed kursorem — liczone na wyniku, więc literały się nie liczą.
+    let significant = 0;
+    for (let i = 0; i < before.length; i += 1)
+        if (KPT_MASK_TOKENS[mask[i]])
+            significant += 1;
+    let seen = 0;
+    for (let i = 0; i < formatted.length; i += 1) {
+        if (KPT_MASK_TOKENS[mask[i]]) {
+            if (seen === significant)
+                return i;
+            seen += 1;
+        }
+    }
+    return formatted.length;
+}

package/dist/internal/number-group.d.ts

@@ -0,0 +1,22 @@
+/** Grupowanie włączone, gdy grupa ma co najmniej jedną cyfrę, a separator nie jest pusty. */
+export interface KptDigitGrouping {
+    readonly size: number;
+    readonly separator: string;
+}
+/**
+ * Zdejmuje separatory grup. Wiodący znak `-`/`+` zostaje nawet wtedy, gdy separatorem jest `-`
+ * (`-123-456` → `-123456`), bo na początku to znak liczby, a nie granica grupy.
+ */
+export declare function kptStripGroups(text: string, separator: string): string;
+/**
+ * Wstawia separator co `size` cyfr części całkowitej, licząc od prawej — tak jak tysiące:
+ * `123456789` → `123-456-789`, `1234` → `1-234`. Część ułamkowa (po `.` albo `,`) i znak zostają
+ * bez zmian. Tekst, który nie wygląda na liczbę w trakcie pisania, wraca nietknięty.
+ */
+export declare function kptGroupDigits(text: string, grouping: KptDigitGrouping): string;
+/**
+ * Pozycja kursora po przeformatowaniu: tyle samo „znaczących” znaków (cyfry, znak, przecinek
+ * dziesiętny) przed kursorem co w tekście sprzed grupowania. Bez tego wstawiony separator
+ * przesuwałby kursor o jedno miejsce przy każdej trzeciej cyfrze.
+ */
+export declare function kptCaretAfterGrouping(before: string, caret: number, after: string, separator: string): number;

package/dist/internal/number-group.js

@@ -0,0 +1,53 @@
+/*
+ * Grupowanie cyfr w polu liczbowym (`kpt-input-number`, `groupSize` + `groupSeparator`).
+ * Bliźniak: packages/angular/src/lib/shared/number-group.ts — zmiana tutaj wymaga zmiany tam.
+ */
+/**
+ * Zdejmuje separatory grup. Wiodący znak `-`/`+` zostaje nawet wtedy, gdy separatorem jest `-`
+ * (`-123-456` → `-123456`), bo na początku to znak liczby, a nie granica grupy.
+ */
+export function kptStripGroups(text, separator) {
+    if (!separator)
+        return text;
+    const sign = /^[-+]/.exec(text)?.[0] ?? '';
+    return sign + text.slice(sign.length).split(separator).join('');
+}
+/**
+ * Wstawia separator co `size` cyfr części całkowitej, licząc od prawej — tak jak tysiące:
+ * `123456789` → `123-456-789`, `1234` → `1-234`. Część ułamkowa (po `.` albo `,`) i znak zostają
+ * bez zmian. Tekst, który nie wygląda na liczbę w trakcie pisania, wraca nietknięty.
+ */
+export function kptGroupDigits(text, grouping) {
+    const { size, separator } = grouping;
+    if (size < 1 || !separator)
+        return text;
+    const match = /^([-+]?)(\d*)([.,]\d*)?$/.exec(kptStripGroups(text, separator));
+    if (!match)
+        return text;
+    const [, sign, integer, fraction = ''] = match;
+    const groups = [];
+    for (let end = integer.length; end > 0; end -= size)
+        groups.unshift(integer.slice(Math.max(0, end - size), end));
+    return sign + groups.join(separator) + fraction;
+}
+/**
+ * Pozycja kursora po przeformatowaniu: tyle samo „znaczących” znaków (cyfry, znak, przecinek
+ * dziesiętny) przed kursorem co w tekście sprzed grupowania. Bez tego wstawiony separator
+ * przesuwałby kursor o jedno miejsce przy każdej trzeciej cyfrze.
+ */
+export function kptCaretAfterGrouping(before, caret, after, separator) {
+    const significant = kptStripGroups(before.slice(0, caret), separator).length;
+    let seen = 0;
+    let index = 0;
+    // Wiodący znak liczby liczy się zawsze, nawet gdy jest identyczny z separatorem.
+    if (significant > 0 && /^[-+]/.test(after)) {
+        seen = 1;
+        index = 1;
+    }
+    while (index < after.length && seen < significant) {
+        if (!after.startsWith(separator, index))
+            seen += 1;
+        index += after.startsWith(separator, index) ? separator.length : 1;
+    }
+    return index;
+}

package/dist/internal/option-key.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Klucz Reacta dla opcji kontrolki generycznej: wartość prymitywna jako tekst, obiekt — pozycja.
+ * `String(obiekt)` dawałby „[object Object]” dla każdej opcji, czyli zdublowane klucze i stan
+ * przenoszony między opcjami przy zmianie listy.
+ */
+export declare function optionKey(value: unknown, index: number): string;

package/dist/internal/option-key.js

@@ -0,0 +1,8 @@
+/**
+ * Klucz Reacta dla opcji kontrolki generycznej: wartość prymitywna jako tekst, obiekt — pozycja.
+ * `String(obiekt)` dawałby „[object Object]” dla każdej opcji, czyli zdublowane klucze i stan
+ * przenoszony między opcjami przy zmianie listy.
+ */
+export function optionKey(value, index) {
+    return typeof value === 'object' && value !== null ? `#${index}` : String(value);
+}

package/dist/internal/overlay.js

@@ -1,7 +1,19 @@
+'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { useKptOverlayContainer } from "./overlay-container.js";
+/*
+ * Prymityw nakładki: panel przypięty do wyzwalacza, renderowany w portalu do `document.body`.
+ *
+ * Port Angulara stoi tu na CDK Overlay, którego w Reakcie nie ma. Odtwarzamy jego zachowanie:
+ * pozycjonowanie względem wyzwalacza z odbiciem w górę, gdy pod spodem brakuje miejsca,
+ * przezroczysty backdrop zamykający kliknięciem oraz Escape. Style samego panelu pochodzą
+ * ze wspólnego arkusza (`.kpt-select__panel`, `.kpt-popover__panel`) — tutaj są wyłącznie
+ * współrzędne, więc nic nie duplikuje wyglądu.
+ */
+/** Otwarte nakładki od najstarszej — Escape obsługuje tylko ostatnia. */
+const overlayStack = [];
 /** Ta sama warstwa co `--kpt-z-overlay` w tokenach — panel ma być nad treścią aplikacji. */
 const Z_INDEX = 'var(--kpt-z-overlay, 1100)';
 export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, minAnchorWidth = false, offset = 4, align = 'start', withBackdrop = true, preferAbove = false, children, }) {
@@ -27,12 +39,17 @@ export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, mi
             ...(minAnchorWidth ? { minWidth: rect.width } : {}),
         });
     }, [anchor, matchAnchorWidth, minAnchorWidth, offset, align, preferAbove]);
-    useLayoutEffect(() => {
-        if (!open) {
+    // Zamknięcie zeruje pozycję w tym samym renderze (wzorzec „poprzednia wartość w stanie”), więc
+    // ponowne otwarcie nie pokaże panelu na klatkę w starym miejscu — bez setState w efekcie.
+    const [wasOpen, setWasOpen] = useState(open);
+    if (wasOpen !== open) {
+        setWasOpen(open);
+        if (!open)
             setPosition(null);
-            return;
-        }
-        update();
+    }
+    useLayoutEffect(() => {
+        if (open)
+            update();
     }, [open, update]);
     useEffect(() => {
         if (!open)
@@ -41,15 +58,28 @@ export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, mi
         // `capture` łapie też przewijanie kontenerów w środku strony, nie tylko okna.
         window.addEventListener('scroll', onScrollOrResize, true);
         window.addEventListener('resize', onScrollOrResize);
+        /*
+         * Escape zamyka tylko najwyższą nakładkę (stos jak `OverlayKeyboardDispatcher` w CDK) i tylko
+         * wtedy, gdy komponent nie obsłużył klawisza sam. `preventDefault` jest konieczne: natywny
+         * `<dialog>` traktuje ten sam Escape jako żądanie zamknięcia — popover w `KptDialog` zamykał
+         * razem ze sobą całe okno.
+         */
+        const token = {};
+        overlayStack.push(token);
         const onKeyDown = (event) => {
-            if (event.key === 'Escape')
-                onClose();
+            if (event.key !== 'Escape' || event.defaultPrevented)
+                return;
+            if (overlayStack[overlayStack.length - 1] !== token)
+                return;
+            event.preventDefault();
+            onClose();
         };
         document.addEventListener('keydown', onKeyDown);
         return () => {
             window.removeEventListener('scroll', onScrollOrResize, true);
             window.removeEventListener('resize', onScrollOrResize);
             document.removeEventListener('keydown', onKeyDown);
+            overlayStack.splice(overlayStack.indexOf(token), 1);
         };
     }, [open, update, onClose]);
     if (!open || !container)

package/dist/internal/password-strength.d.ts

@@ -0,0 +1,6 @@
+/** 0 = bardzo słabe … 4 = silne. */
+export type KptPasswordScore = 0 | 1 | 2 | 3 | 4;
+/** Przybliżona entropia w bitach. */
+export declare function kptPasswordBits(value: string): number;
+/** Wynik 0–4 z entropii: <28 bardzo słabe, <36 słabe, <50 średnie, <64 dobre, reszta silne. */
+export declare function kptPasswordScore(value: string): KptPasswordScore;

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/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/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.js

@@ -5,6 +5,7 @@
  * 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.
  */
+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. */
@@ -34,7 +35,5 @@ export function kptTween(from, to, duration, onFrame) {
 }
 /** 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/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;