@konce-pt/react 0.11.2 → 0.14.0

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

@@ -1,53 +1,75 @@
-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.
+ * Pole kodu jednorazowego (OTP/PIN) - N osobnych pól, automatyczne przejście do następnego
+ * 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();
     };
-    /** Wpisuje `text` od komórki `start` (bez spacji i — przy `integerOnly` — bez nie-cyfr). */
+    /** 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(/ +$/, ''));
-        // 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();
+        commitCells(arr);
+        // Fokus na pierwszą pustą komórkę, a przy komplecie - na ostatnią.
+        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
+        // 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.
         if (el.value.length > 1 && !(el.value.length === 2 && charAt(index))) {
             const text = el.value;
@@ -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,13 +98,15 @@ 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. */
+    /** "Dotknięcie" dopiero przy wyjściu fokusu z całej grupy, nie przy przejściu między komórkami. */
     const onGroupBlur = (event) => {
         const next = event.relatedTarget;
         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

@@ -1,25 +1,25 @@
 # KptInputOtp (@konce-pt/react)
 
-A one-time code field (OTP / PIN) — N separate boxes, auto-advance and paste.
+A one-time code field (OTP / PIN) - N separate boxes, auto-advance and paste.
 Import: `import { KptInputOtp } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-input-otp-host">
       <div class="kpt-input-otp">
         <input class="kpt-input-otp__cell" type="text" inputmode="numeric" maxlength="1" value="1">
-        …N cells…
+        ...N cells...
       </div>
     </div>
 
 ## Props
-- `value` / `defaultValue` / `onValueChange` — one string, the characters joined
+- `value` / `defaultValue` / `onValueChange` - one string, the characters joined
 - `length`: number (default 6)
-- `integerOnly`: boolean — digits only, and a numeric keyboard on mobile
+- `integerOnly`: boolean - digits only, and a numeric keyboard on mobile
 - `disabled`, `invalid`, `touched`, `onTouch()`
 
 ## One string, N boxes
 The value is a single string while the UI is N inputs, so a gap in the middle has to be
-expressible. Writing pads with spaces, replaces the character and trims trailing spaces — that way
+expressible. Writing pads with spaces, replaces the character and trims trailing spaces - that way
 a code with a hole round-trips and a single character does not turn into one followed by blanks.
 
 The DOM of a cell is also synced by hand after a rejected character: the value did not change, so
@@ -28,7 +28,7 @@ React has nothing to re-render, and the typed character would otherwise stay on
 ## Keyboard and paste
 A character moves focus to the next cell; Backspace in an empty cell moves back; ArrowLeft and
 ArrowRight walk the cells; focus selects the content so typing overwrites. Pasting fills the whole
-code at once — with `integerOnly` everything non-numeric is stripped first, so a copied
+code at once - with `integerOnly` everything non-numeric is stripped first, so a copied
 "123-456" still lands correctly.
 
 ## Examples
@@ -38,7 +38,7 @@ code at once — with `integerOnly` everything non-numeric is stripped first, so
 ## Screen reader and keyboard
 The first cell has `autocomplete="one-time-code"`, so phones offer the code from an SMS; a code that
 arrives in one cell at once (autofill, an on-screen keyboard paste) is spread over the cells like a
-paste. `touch` fires when focus leaves the whole group — not after a paste, and not when moving
+paste. `touch` fires when focus leaves the whole group - not after a paste, and not when moving
 between cells.
 
 ## Label and description
@@ -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/calendar-focus.d.ts

@@ -1,7 +1,7 @@
 /** Zawija `Tab` / `Shift+Tab` w obrębie `panel`. */
 export declare function trapTab(panel: HTMLElement, event: KeyboardEvent): void;
 /**
- * Fokus na „aktywną” komórkę panelu: dzień `iso`, przystanek siatki komórek, a bez nich — pierwszy
+ * Fokus na "aktywną" komórkę panelu: dzień `iso`, przystanek siatki komórek, a bez nich - pierwszy
  * element panelu (zegar). Panel w nakładce jest niewidoczny do pierwszego pomiaru, więc wołający
  * odkłada to na `requestAnimationFrame`.
  */

package/dist/internal/calendar-focus.js

@@ -1,9 +1,9 @@
 /*
- * Fokus w panelu kalendarza — wspólny dla `KptDatepicker` i `KptDateRange`. Panel stoi
+ * Fokus w panelu kalendarza - wspólny dla `KptDatepicker` i `KptDateRange`. Panel stoi
  * w nakładce na końcu strony, więc `Tab` z ostatniego elementu uciekłby poza niego; zawijamy go
  * w obrębie panelu, jak w oknie dialogowym.
  *
- * Bliźniak w porcie Angulara: `shared/calendar-focus.ts` — zmiana zachowania w obu.
+ * Bliźniak w porcie Angulara: `shared/calendar-focus.ts` - zmiana zachowania w obu.
  */
 const FOCUSABLE = 'button:not(:disabled):not([tabindex="-1"]), input:not(:disabled), [tabindex="0"]';
 /** Zawija `Tab` / `Shift+Tab` w obrębie `panel`. */
@@ -24,7 +24,7 @@ export function trapTab(panel, event) {
     }
 }
 /**
- * Fokus na „aktywną” komórkę panelu: dzień `iso`, przystanek siatki komórek, a bez nich — pierwszy
+ * Fokus na "aktywną" komórkę panelu: dzień `iso`, przystanek siatki komórek, a bez nich - pierwszy
  * element panelu (zegar). Panel w nakładce jest niewidoczny do pierwszego pomiaru, więc wołający
  * odkłada to na `requestAnimationFrame`.
  */

package/dist/internal/cn.d.ts

@@ -1,5 +1,5 @@
 /**
- * Sklejanie klas CSS. Odpowiednik `clsx` w kilkunastu linijkach — biblioteka
+ * Sklejanie klas CSS. Odpowiednik `clsx` w kilkunastu linijkach - biblioteka
  * zostaje bez zależności runtime, a konsument nie ryzykuje konfliktu wersji.
  *
  * Wartości fałszywe są pomijane, tablice spłaszczane, duplikaty usuwane

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

@@ -1,16 +1,16 @@
 /** Klawisze, które przesuwają aktywną opcję. */
 export declare const OPTION_NAV_KEYS: Set<string>;
 /**
- * Indeks opcji po klawiszu `key`, z pominięciem wyłączonych (`disabled[i]`). Bez zawijania — na
- * końcu listy strzałka zostaje na miejscu, jak w natywnym `<select>`. `current` = -1 znaczy „nic
- * aktywnego”: `↓` idzie wtedy na pierwszą, `↑` na ostatnią. `null` dla innych klawiszy albo listy
+ * Indeks opcji po klawiszu `key`, z pominięciem wyłączonych (`disabled[i]`). Bez zawijania - na
+ * końcu listy strzałka zostaje na miejscu, jak w natywnym `<select>`. `current` = -1 znaczy "nic
+ * aktywnego": `ArrowDown` idzie wtedy na pierwszą, `ArrowUp` na ostatnią. `null` dla innych klawiszy albo listy
  * bez aktywnych opcji.
  */
 export declare function nextOptionIndex(disabled: readonly boolean[], current: number, key: string): number | null;
 /**
  * Wyszukiwanie po pierwszych literach (type-ahead): pierwsza aktywna opcja zaczynająca się od
  * `query`, licząc od pozycji za `current` i zawijając. Porównanie bez wielkości liter i polskich
- * znaków — „lo” znajduje „Łódź”.
+ * znaków - "lo" znajduje "Łódź".
  */
 export declare function typeaheadIndex(labels: readonly string[], disabled: readonly boolean[], current: number, query: string): number | null;
 /** Bufor wpisywanych liter dla type-ahead: zeruje się po chwili bez pisania. */

package/dist/internal/option-nav.js

@@ -1,5 +1,5 @@
 /*
- * Nawigacja klawiaturą po liście opcji z aktywną pozycją (`aria-activedescendant`) — wspólna dla
+ * Nawigacja klawiaturą po liście opcji z aktywną pozycją (`aria-activedescendant`) - wspólna dla
  * `KptSelect`, `KptListbox` i `KptAutocomplete`. Port Angulara ma bliźniaczy plik
  * `shared/option-nav.ts`. Fokus zostaje na kontrolce; zmienia się tylko indeks aktywnej opcji.
  */
@@ -9,9 +9,9 @@ const PAGE = 10;
 /** Klawisze, które przesuwają aktywną opcję. */
 export const OPTION_NAV_KEYS = new Set(['ArrowDown', 'ArrowUp', 'Home', 'End', 'PageDown', 'PageUp']);
 /**
- * Indeks opcji po klawiszu `key`, z pominięciem wyłączonych (`disabled[i]`). Bez zawijania — na
- * końcu listy strzałka zostaje na miejscu, jak w natywnym `<select>`. `current` = -1 znaczy „nic
- * aktywnego”: `↓` idzie wtedy na pierwszą, `↑` na ostatnią. `null` dla innych klawiszy albo listy
+ * Indeks opcji po klawiszu `key`, z pominięciem wyłączonych (`disabled[i]`). Bez zawijania - na
+ * końcu listy strzałka zostaje na miejscu, jak w natywnym `<select>`. `current` = -1 znaczy "nic
+ * aktywnego": `ArrowDown` idzie wtedy na pierwszą, `ArrowUp` na ostatnią. `null` dla innych klawiszy albo listy
  * bez aktywnych opcji.
  */
 export function nextOptionIndex(disabled, current, key) {
@@ -47,7 +47,7 @@ export function nextOptionIndex(disabled, current, key) {
 /**
  * Wyszukiwanie po pierwszych literach (type-ahead): pierwsza aktywna opcja zaczynająca się od
  * `query`, licząc od pozycji za `current` i zawijając. Porównanie bez wielkości liter i polskich
- * znaków — „lo” znajduje „Łódź”.
+ * znaków - "lo" znajduje "Łódź".
  */
 export function typeaheadIndex(labels, disabled, current, query) {
     const q = foldMentionText(query);

package/dist/internal/overlay-container.js

@@ -3,7 +3,7 @@ import { createContext, useContext } from 'react';
  * Miejsce, do którego portalują się panele nakładek.
  *
  * `showModal()` wynosi `<dialog>` do warstwy szczytowej przeglądarki, a ta stoi ponad całym
- * drzewem dokumentu — żaden `z-index` tego nie przebije. Panel selecta czy menu otwarty
+ * drzewem dokumentu - żaden `z-index` tego nie przebije. Panel selecta czy menu otwarty
  * z wnętrza modala portalowałby się na `document.body` i byłby NIEWIDOCZNY, schowany za tłem
  * okna. `KptDialog` podstawia więc siebie jako kontener na czas, gdy jest otwarty.
  *

package/dist/internal/overlay.d.ts

@@ -5,7 +5,7 @@ export interface KptOverlayProps {
     anchor: HTMLElement | null;
     /** Kliknięcie w backdrop albo Escape. */
     onClose: () => void;
-    /** Panel dostaje szerokość wyzwalacza — dokładnie tę (podpowiedzi autocomplete pod polem). */
+    /** Panel dostaje szerokość wyzwalacza - dokładnie tę (podpowiedzi autocomplete pod polem). */
     matchAnchorWidth?: boolean;
     /**
      * Panel jest co najmniej tak szeroki jak wyzwalacz, ale rośnie do treści (lista selecta:
@@ -16,13 +16,13 @@ export interface KptOverlayProps {
     offset?: number;
     /**
      * Krawędź, do której wyrównujemy panel: `start` (lewa, domyślnie) albo `end` (prawa).
-     * `end` przydaje się, gdy wyzwalacz siedzi przy prawej krawędzi kontrolki — panel otwiera się
+     * `end` przydaje się, gdy wyzwalacz siedzi przy prawej krawędzi kontrolki - panel otwiera się
      * wtedy w lewo i nie wychodzi poza nią.
      */
     align?: 'start' | 'end';
     /**
      * Przezroczysty backdrop przechwytujący kliknięcie poza panelem. Wyłącz go tam, gdzie panel
-     * ma zostawić wyzwalacz klikalnym — autocomplete zamyka się na `blur` pola, a backdrop
+     * ma zostawić wyzwalacz klikalnym - autocomplete zamyka się na `blur` pola, a backdrop
      * zasłoniłby to pole i zabrałby mu każde kliknięcie.
      */
     withBackdrop?: boolean;

package/dist/internal/overlay.js

@@ -1,8 +1,20 @@
+'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";
-/** Ta sama warstwa co `--kpt-z-overlay` w tokenach — panel ma być nad treścią aplikacji. */
+/*
+ * 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, }) {
     const container = useKptOverlayContainer();
@@ -16,7 +28,7 @@ export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, mi
         const panelWidth = panelRef.current?.offsetWidth ?? 0;
         const below = window.innerHeight - rect.bottom;
         // Odbicie w górę tylko wtedy, gdy pod spodem naprawdę brakuje miejsca, a nad wyzwalaczem
-        // jest go więcej — inaczej panel skakałby przy każdym przewinięciu o kilka pikseli.
+        // jest go więcej - inaczej panel skakałby przy każdym przewinięciu o kilka pikseli.
         // Przy `preferAbove` jest odwrotnie: panel stoi nad wyzwalaczem, dopóki się tam mieści.
         const fitsAbove = panelHeight === 0 || rect.top > panelHeight + offset;
         const flip = preferAbove ? fitsAbove : panelHeight > 0 && below < panelHeight + offset && rect.top > below;
@@ -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)
@@ -61,7 +91,7 @@ export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, mi
                     width: position?.width,
                     minWidth: position?.minWidth,
                     zIndex: Z_INDEX,
-                    // Panel bez pozycji jeszcze nie został zmierzony — chowamy go na pierwszej klatce,
+                    // Panel bez pozycji jeszcze nie został zmierzony - chowamy go na pierwszej klatce,
                     // żeby nie mrugnął w lewym górnym rogu.
                     visibility: position ? 'visible' : 'hidden',
                 }, children: children })] }), 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;