@konce-pt/react 0.9.0 → 0.10.0

package/dist/input-number/input-number.d.ts

@@ -12,6 +12,12 @@ export interface KptInputNumberProps extends Omit<ComponentPropsWithRef<'div'>,
     suffix?: string;
     /** Przyciski krokowania. `false` daje samo pole — wariant do zakresów „od–do". */
     showButtons?: boolean;
+    /** 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;
+    /** Oznacza pole jako wymagane atrybutem `aria-required`. */
+    required?: boolean;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -21,8 +27,14 @@ export interface KptInputNumberProps extends Omit<ComponentPropsWithRef<'div'>,
  * Pole liczbowe ze strzałkami krokowania. Wartość to `number | null` — puste pole ma znaczenie,
  * bo „brak wartości" to nie to samo co zero.
  *
+ * Pole to `role="spinbutton"` (z `aria-valuemin`/`max`/`now`, a przy `suffix` — `aria-valuetext`):
+ * `↑`/`↓` zmieniają wartość o `step`, `PageUp`/`PageDown` o dziesięć kroków. Wpisywana liczba nie
+ * jest przycinana w trakcie pisania (inaczej „150” przy `max` 99 stawało się „99”, zanim user skończył) —
+ * granice działają przy krokowaniu i na `blur`. Przyciski `−`/`+` stoją poza kolejnością Tab i nie
+ * zabierają fokusu polu.
+ *
  * @example
  * <KptInputNumber value={qty} onValueChange={setQty} min={0} max={99} suffix=" szt." />
  * <KptInputNumber value={from} onValueChange={setFrom} showButtons={false} suffix=" zł" />
  */
-export declare function KptInputNumber({ value, defaultValue, onValueChange, min, max, step, placeholder, suffix, showButtons, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptInputNumberProps>): import("react").JSX.Element;
+export declare function KptInputNumber({ value, defaultValue, onValueChange, min, max, step, placeholder, suffix, showButtons, id, ariaLabel, required, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptInputNumberProps>): import("react").JSX.Element;

package/dist/input-number/input-number.js

@@ -1,25 +1,35 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback } from 'react';
+import { useCallback, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
 /**
  * Pole liczbowe ze strzałkami krokowania. Wartość to `number | null` — puste pole ma znaczenie,
  * bo „brak wartości" to nie to samo co zero.
  *
+ * Pole to `role="spinbutton"` (z `aria-valuemin`/`max`/`now`, a przy `suffix` — `aria-valuetext`):
+ * `↑`/`↓` zmieniają wartość o `step`, `PageUp`/`PageDown` o dziesięć kroków. Wpisywana liczba nie
+ * jest przycinana w trakcie pisania (inaczej „150” przy `max` 99 stawało się „99”, zanim user skończył) —
+ * granice działają przy krokowaniu i na `blur`. Przyciski `−`/`+` stoją poza kolejnością Tab i nie
+ * zabierają fokusu polu.
+ *
  * @example
  * <KptInputNumber value={qty} onValueChange={setQty} min={0} max={99} suffix=" szt." />
  * <KptInputNumber value={from} onValueChange={setFrom} showButtons={false} suffix=" zł" />
  */
-export function KptInputNumber({ value, defaultValue = null, onValueChange, min, max, step = 1, placeholder = '', suffix = '', showButtons = true, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
-    const { t } = useKptMessages({ locale, dictionary });
+export function KptInputNumber({ value, defaultValue = null, onValueChange, min, max, step = 1, placeholder = '', suffix = '', showButtons = true, id, ariaLabel = null, required = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+    const { t, locale: activeLocale } = useKptMessages({ locale, dictionary });
+    const field = useKptFieldA11y(id, 'kpt-input-number');
     const [current, setCurrent] = useControllableState({
         value,
         defaultValue,
         onChange: onValueChange,
     });
     const showInvalid = invalid && (touched ?? true);
+    /** Tekst w trakcie pisania — dopóki jest, pole pokazuje go zamiast sformatowanej wartości. */
+    const [draft, setDraft] = useState(null);
     const clamp = useCallback((n) => {
         if (min !== undefined && n < min)
             return min;
@@ -27,26 +37,56 @@ export function KptInputNumber({ value, defaultValue = null, onValueChange, min,
             return max;
         return n;
     }, [min, max]);
-    const display = current === null || current === undefined || Number.isNaN(current) ? '' : `${current}${suffix}`;
+    // Zapis liczby wg aktywnego języka (PL: `12,5`), bez separatorów tysięcy — pole przyjmuje i kropkę,
+    // i przecinek, a grupowanie cyfr rozjechałoby się z tym, co user wpisuje.
+    const format = new Intl.NumberFormat(activeLocale, { useGrouping: false, maximumFractionDigits: 20 });
+    const display = current === null || current === undefined || Number.isNaN(current) ? '' : `${format.format(current)}${suffix}`;
     const canIncrement = max === undefined || (current ?? -Infinity) < max;
     const canDecrement = min === undefined || (current ?? Infinity) > min;
     const onInput = (event) => {
         // Przecinek jako separator dziesiętny i dopisek trafiają do pola razem z liczbą —
         // czyścimy je przed parsowaniem, żeby wpisywanie „12,5 zł" działało naturalnie.
+        setDraft(event.target.value);
         const raw = event.target.value.replace(suffix, '').replace(',', '.').trim();
         if (raw === '') {
             setCurrent(null);
             return;
         }
+        // Bez przycinania: wartość spoza granic zostaje, a walidacja formularza ją zgłosi.
         const parsed = Number(raw);
         if (!Number.isNaN(parsed))
-            setCurrent(clamp(parsed));
+            setCurrent(parsed);
     };
-    const stepBy = (direction) => {
+    const stepBy = (count) => {
         const base = current ?? min ?? 0;
-        setCurrent(clamp(base + direction * step));
+        // Zaokrąglenie do precyzji kroku — 0.1 + 0.2 nie może dać 0.30000000000000004.
+        const decimals = (String(step).split('.')[1] ?? '').length;
+        setDraft(null);
+        setCurrent(clamp(Number((base + count * step).toFixed(decimals))));
+    };
+    const onKeyDown = (event) => {
+        const steps = { ArrowUp: 1, ArrowDown: -1, PageUp: 10, PageDown: -10 };
+        const count = steps[event.key];
+        if (count === undefined || disabled)
+            return;
+        event.preventDefault();
+        stepBy(count);
+    };
+    /** Wyjście z pola: przycięcie do granic i sformatowany zapis. */
+    const onBlur = () => {
+        if (current !== null && current !== undefined && !Number.isNaN(current)) {
+            const clamped = clamp(current);
+            if (clamped !== current)
+                setCurrent(clamped);
+        }
+        setDraft(null);
         onTouch?.();
     };
-    const onBlur = (_event) => onTouch?.();
-    return (_jsx("div", { className: cn('kpt-input-number-host', className), ...rest, children: _jsxs("div", { className: cn('kpt-input-number', disabled && 'kpt-input-number--disabled', showInvalid && 'kpt-input-number--invalid', !showButtons && 'kpt-input-number--plain'), children: [showButtons ? (_jsx("button", { type: "button", className: "kpt-input-number__btn", disabled: disabled || !canDecrement, onClick: () => stepBy(-1), "aria-label": t('inputNumber.decrement'), children: _jsx(KptIcon, { name: "minus" }) })) : null, _jsx("input", { className: "kpt-input-number__input", type: "text", inputMode: "decimal", value: display, disabled: disabled, placeholder: placeholder, onChange: onInput, onBlur: onBlur }), showButtons ? (_jsx("button", { type: "button", className: "kpt-input-number__btn", disabled: disabled || !canIncrement, onClick: () => stepBy(1), "aria-label": t('inputNumber.increment'), children: _jsx(KptIcon, { name: "plus" }) })) : null] }) }));
+    return (_jsx("div", { className: cn('kpt-input-number-host', className), ...rest, children: _jsxs("div", { className: cn('kpt-input-number', disabled && 'kpt-input-number--disabled', showInvalid && 'kpt-input-number--invalid', !showButtons && 'kpt-input-number--plain'), children: [showButtons ? (_jsx("button", { type: "button", className: "kpt-input-number__btn", tabIndex: -1, disabled: disabled || !canDecrement, onMouseDown: (event) => event.preventDefault(), onClick: () => {
+                        stepBy(-1);
+                        onTouch?.();
+                    }, "aria-label": t('inputNumber.decrement'), children: _jsx(KptIcon, { name: "minus" }) })) : null, _jsx("input", { className: "kpt-input-number__input", id: field.id, "aria-label": ariaLabel ?? undefined, "aria-required": required || undefined, "aria-invalid": showInvalid || undefined, "aria-describedby": field.describedBy, type: "text", inputMode: "decimal", role: "spinbutton", "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": current ?? undefined, "aria-valuetext": suffix && current !== null ? display : undefined, value: draft ?? display, disabled: disabled, placeholder: placeholder, onChange: onInput, onKeyDown: onKeyDown, onBlur: onBlur }), showButtons ? (_jsx("button", { type: "button", className: "kpt-input-number__btn", tabIndex: -1, disabled: disabled || !canIncrement, onMouseDown: (event) => event.preventDefault(), onClick: () => {
+                        stepBy(1);
+                        onTouch?.();
+                    }, "aria-label": t('inputNumber.increment'), children: _jsx(KptIcon, { name: "plus" }) })) : null] }) }));
 }

package/dist/input-number/llms.txt

@@ -27,7 +27,7 @@ nothing to step from.
 ## A text input, not a number input
 The field is `type="text"` with `inputmode="decimal"`, so the suffix can live inside it and a comma
 works as the decimal separator — typing "12,5 zł" parses correctly. A native `type="number"` would
-reject both. Values out of range are clamped on input, not rejected.
+reject both. Values out of range are clamped on blur and when stepping — not while typing.
 
 ## i18n
 The stepper labels come from `inputNumber.decrement` and `inputNumber.increment`.
@@ -36,9 +36,27 @@ The stepper labels come from `inputNumber.decrement` and `inputNumber.increment`
     <KptInputNumber value={qty} onValueChange={setQty} min={0} max={99} />
     <KptInputNumber value={price} onValueChange={setPrice} showButtons={false} suffix=" zł" />
 
+## Keyboard
+The field is `role="spinbutton"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow` (and
+`aria-valuetext` with the `suffix`, "5 pcs"). `↑`/`↓` change the value by `step`,
+`PageUp`/`PageDown` by ten steps; stepping is rounded to the precision of `step`. A typed value is
+**not** clamped while typing ("150" with `max` 99 stays "150", so the form's `max()` can report it) —
+it is clamped on blur. The `−`/`+` buttons sit outside the Tab order and do not take focus from the
+field, so focus never drops to `<body>` when a button goes disabled at a limit.
+
+## Screen reader and keyboard
+The value is shown in the active locale's notation (PL `12,5`), without thousands separators — the
+field accepts both a dot and a comma, and digit grouping would clash with what the user types.
+
+## Label and description
+`id` goes to the native field, not the host; without one it comes from `KptFormField` or is
+generated. Inside `KptFormField` the wrapper's `label[for]` points at it and the hint or error is
+added to `aria-describedby` (merged with your own). Without a wrapper, name it with `ariaLabel`.
+New: `id`, `ariaLabel`, `required` and `aria-invalid` on the field.
+
 ## Tokens
 `--kpt-form-field-{bg,text,border,border-focus,border-error,radius}`.
 
 ## Accessibility
-The stepper buttons carry labels from the dictionary and go `disabled` at the limits, so the
-keyboard never lands on a control that cannot do anything.
+The field is a `spinbutton` (see Keyboard). The stepper buttons carry labels from the dictionary,
+sit outside the Tab order and go `disabled` at the limits without stealing focus from the field.

package/dist/input-otp/input-otp.d.ts

@@ -1,11 +1,16 @@
 import type { ComponentPropsWithRef } from 'react';
-export interface KptInputOtpProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+export interface KptInputOtpProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'>, KptI18nOverrides {
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
     length?: number;
     /** Dopuszcza wyłącznie cyfry i przełącza klawiaturę mobilną na numeryczną. */
     integerOnly?: boolean;
+    /** Id pierwszej komórki (nie hosta) — klik w etykietę zaczyna wpisywanie od początku. */
+    id?: string;
+    /** Nazwa grupy komórek, gdy nie opisuje jej etykieta (`KptFormField`). */
+    ariaLabel?: string | null;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -18,4 +23,4 @@ export interface KptInputOtpProps extends Omit<ComponentPropsWithRef<'div'>, 'on
  * @example
  * <KptInputOtp value={code} onValueChange={setCode} length={6} integerOnly />
  */
-export declare function KptInputOtp({ value, defaultValue, onValueChange, length, integerOnly, disabled, invalid, touched, onTouch, className, ...rest }: Readonly<KptInputOtpProps>): import("react").JSX.Element;
+export declare function KptInputOtp({ value, defaultValue, onValueChange, length, integerOnly, id, ariaLabel, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptInputOtpProps>): import("react").JSX.Element;

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

@@ -1,6 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 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.
@@ -8,7 +10,9 @@ import { useControllableState } from "../internal/use-controllable-state.js";
  * @example
  * <KptInputOtp value={code} onValueChange={setCode} length={6} integerOnly />
  */
-export function KptInputOtp({ value, defaultValue = '', onValueChange, length = 6, integerOnly = false, disabled = false, invalid = false, touched, onTouch, className, ...rest }) {
+export function KptInputOtp({ value, defaultValue = '', onValueChange, length = 6, integerOnly = false, id, ariaLabel = null, disabled = 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] ?? '';
@@ -26,8 +30,31 @@ export function KptInputOtp({ value, defaultValue = '', onValueChange, length =
         const target = direction === 1 ? el.nextElementSibling : el.previousElementSibling;
         target?.focus();
     };
+    /** 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('');
+        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();
+    };
     const onInput = (index, event) => {
         const el = event.target;
+        // 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.
+        if (el.value.length > 1 && !(el.value.length === 2 && charAt(index))) {
+            const text = el.value;
+            el.value = charAt(index);
+            fillFrom(index, text, el);
+            return;
+        }
         let char = el.value.slice(-1);
         if (integerOnly && !/\d/.test(char))
             char = '';
@@ -49,11 +76,13 @@ export function KptInputOtp({ value, defaultValue = '', onValueChange, length =
     };
     const onPaste = (event) => {
         event.preventDefault();
-        let text = event.clipboardData.getData('text');
-        if (integerOnly)
-            text = text.replace(/\D/g, '');
-        setCurrent(text.slice(0, length));
-        onTouch?.();
+        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. */
+    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'), children: Array.from({ length }, (_, index) => (_jsx("input", { className: "kpt-input-otp__cell", type: "text", inputMode: integerOnly ? 'numeric' : 'text', maxLength: 1, 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) => (_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))) }) }));
 }

package/dist/input-otp/llms.txt

@@ -35,6 +35,20 @@ code at once — with `integerOnly` everything non-numeric is stripped first, so
     <KptInputOtp value={code} onValueChange={setCode} length={6} integerOnly />
     <KptInputOtp value={code} onValueChange={setCode} length={4} />
 
+## 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
+between cells.
+
+## Label and description
+`id` goes to the focusable element, not the host; without one it comes from `KptFormField` or is
+generated. A `div` with a role is not named by `label[for]`, so inside `KptFormField` it gets
+`aria-labelledby` pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error
+is added to `aria-describedby`. The cells form a named `role="group"`; `id` goes to the first cell
+(clicking the label starts at the beginning), and each cell is named "Character 2 of 6"
+(`inputOtp.cell`).
+
 ## Tokens
 `--kpt-form-field-{bg,text,border,border-focus,border-error,radius}`.
 

package/dist/internal/calendar-focus.d.ts

@@ -0,0 +1,8 @@
+/** 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
+ * element panelu (zegar). Panel w nakładce jest niewidoczny do pierwszego pomiaru, więc wołający
+ * odkłada to na `requestAnimationFrame`.
+ */
+export declare function focusCalendarActive(panel: HTMLElement | null, iso: string): void;

package/dist/internal/calendar-focus.js

@@ -0,0 +1,38 @@
+/*
+ * 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.
+ */
+const FOCUSABLE = 'button:not(:disabled):not([tabindex="-1"]), input:not(:disabled), [tabindex="0"]';
+/** Zawija `Tab` / `Shift+Tab` w obrębie `panel`. */
+export function trapTab(panel, event) {
+    const items = [...panel.querySelectorAll(FOCUSABLE)].filter((el) => el.offsetParent !== null);
+    if (!items.length)
+        return;
+    const first = items[0];
+    const last = items[items.length - 1];
+    const active = document.activeElement;
+    if (event.shiftKey && (active === first || !panel.contains(active))) {
+        event.preventDefault();
+        last.focus();
+    }
+    else if (!event.shiftKey && (active === last || !panel.contains(active))) {
+        event.preventDefault();
+        first.focus();
+    }
+}
+/**
+ * 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`.
+ */
+export function focusCalendarActive(panel, iso) {
+    if (!panel)
+        return;
+    const target = panel.querySelector(`.kpt-calendar__day[data-iso="${iso}"]`) ??
+        panel.querySelector('.kpt-calendar__cell[tabindex="0"]') ??
+        panel.querySelector('button:not(:disabled), [tabindex="0"]');
+    target?.focus();
+}

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

@@ -0,0 +1,24 @@
+/** 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
+ * 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ź”.
+ */
+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. */
+export declare class KptTypeahead {
+    private buffer;
+    private timer;
+    /** Dopisuje znak i zwraca całe zapytanie. */
+    push(char: string): string;
+}
+/** Czy klawisz to pojedynczy znak do wyszukiwania (bez modyfikatorów skrótów). */
+export declare function isTypeaheadKey(event: KeyboardEvent): boolean;

package/dist/internal/option-nav.js

@@ -0,0 +1,80 @@
+/*
+ * 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.
+ */
+import { foldMentionText } from '@konce-pt/mention';
+/** Ile pozycji przeskakuje `PageUp` / `PageDown`. */
+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
+ * bez aktywnych opcji.
+ */
+export function nextOptionIndex(disabled, current, key) {
+    const count = disabled.length;
+    const enabled = (i) => i >= 0 && i < count && !disabled[i];
+    const first = disabled.findIndex((d) => !d);
+    if (first < 0 || !OPTION_NAV_KEYS.has(key))
+        return null;
+    let last = count - 1;
+    while (last >= 0 && disabled[last])
+        last--;
+    const scan = (from, step, fallback) => {
+        for (let i = from; i >= 0 && i < count; i += step)
+            if (enabled(i))
+                return i;
+        return fallback;
+    };
+    switch (key) {
+        case 'Home':
+            return first;
+        case 'End':
+            return last;
+        case 'ArrowDown':
+            return current < 0 ? first : scan(current + 1, 1, current);
+        case 'ArrowUp':
+            return current < 0 ? last : scan(current - 1, -1, current);
+        case 'PageDown':
+            return scan(Math.min(count - 1, Math.max(current, 0) + PAGE), -1, last);
+        default:
+            return scan(Math.max(0, current - PAGE), 1, first);
+    }
+}
+/**
+ * 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ź”.
+ */
+export function typeaheadIndex(labels, disabled, current, query) {
+    const q = foldMentionText(query);
+    if (!q)
+        return null;
+    const count = labels.length;
+    for (let n = 1; n <= count; n++) {
+        const i = (Math.max(current, -1) + n + count) % count;
+        if (!disabled[i] && foldMentionText(labels[i]).startsWith(q))
+            return i;
+    }
+    return null;
+}
+/** Bufor wpisywanych liter dla type-ahead: zeruje się po chwili bez pisania. */
+export class KptTypeahead {
+    buffer = '';
+    timer = null;
+    /** Dopisuje znak i zwraca całe zapytanie. */
+    push(char) {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.buffer += char;
+        this.timer = setTimeout(() => (this.buffer = ''), 500);
+        return this.buffer;
+    }
+}
+/** Czy klawisz to pojedynczy znak do wyszukiwania (bez modyfikatorów skrótów). */
+export function isTypeaheadKey(event) {
+    return event.key.length === 1 && event.key !== ' ' && !event.ctrlKey && !event.metaKey && !event.altKey;
+}

package/dist/internal/roving.d.ts

@@ -0,0 +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
+ * 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. */
+export declare function rovingStop(disabled: readonly boolean[], preferred: number): number;

package/dist/internal/roving.js

@@ -0,0 +1,43 @@
+/*
+ * 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
+ * pierwszego/ostatniego aktywnego. Zwraca `null` dla klawisza, który nie nawiguje, albo gdy nie ma
+ * dokąd przejść.
+ */
+export function nextRovingIndex(disabled, current, key) {
+    const count = disabled.length;
+    const enabled = (i) => !disabled[i];
+    const scan = (from, step) => {
+        for (let n = 0, i = from; n < count; n += 1, i = (i + step + count) % count) {
+            if (enabled(i))
+                return i;
+        }
+        return null;
+    };
+    if (count === 0)
+        return null;
+    switch (key) {
+        case 'Home':
+            return scan(0, 1);
+        case 'End':
+            return scan(count - 1, -1);
+        case 'ArrowRight':
+            return scan((current + 1 + count) % count, 1);
+        case 'ArrowLeft':
+            return scan((current - 1 + count) % count, -1);
+        default:
+            return null;
+    }
+}
+/** 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;
+    const first = disabled.findIndex((d) => !d);
+    return first < 0 ? 0 : first;
+}

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

@@ -0,0 +1,10 @@
+import { type RefObject } from 'react';
+/**
+ * Fokus panelu modalnego (`KptDrawer`, `KptBottomSheet`): przy otwarciu zapamiętuje element
+ * 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ł.
+ *
+ * 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

@@ -0,0 +1,57 @@
+import { useEffect } from 'react';
+/** 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]'));
+}
+/**
+ * Fokus panelu modalnego (`KptDrawer`, `KptBottomSheet`): przy otwarciu zapamiętuje element
+ * 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ł.
+ *
+ * Port Angulara robi to samo na pułapce CDK (`shared/modal-focus.ts`) — zmiana zachowania w obu.
+ */
+export function useModalFocus(open, panelRef) {
+    useEffect(() => {
+        const panel = panelRef.current;
+        if (!open || !panel)
+            return;
+        const active = document.activeElement;
+        const returnTo = active instanceof HTMLElement && !panel.contains(active) ? active : null;
+        // 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(() => {
+            const first = tabbables(panel)[0];
+            (first ?? panel).focus();
+        });
+        const onKeyDown = (event) => {
+            if (event.key !== 'Tab')
+                return;
+            const items = tabbables(panel);
+            if (!items.length) {
+                event.preventDefault();
+                panel.focus();
+                return;
+            }
+            const first = items[0];
+            const last = items[items.length - 1];
+            const current = document.activeElement;
+            if (event.shiftKey && (current === first || !panel.contains(current))) {
+                event.preventDefault();
+                last.focus();
+            }
+            else if (!event.shiftKey && (current === last || !panel.contains(current))) {
+                event.preventDefault();
+                first.focus();
+            }
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => {
+            cancelAnimationFrame(frame);
+            document.removeEventListener('keydown', onKeyDown);
+            if (returnTo?.isConnected)
+                returnTo.focus();
+        };
+    }, [open, panelRef]);
+}

package/dist/knob/knob.d.ts

@@ -13,6 +13,10 @@ 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?: string;
+    /** Nazwa dostępna, gdy kontrolki nie opisuje etykieta (`<label for>` albo `KptFormField`). */
+    ariaLabel?: string | null;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -24,4 +28,4 @@ export interface KptKnobProps extends Omit<ComponentPropsWithRef<'div'>, 'onChan
  * @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, 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, invalid, touched, onTouch, className, ...rest }: Readonly<KptKnobProps>): import("react").JSX.Element;

package/dist/knob/knob.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef } 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";
 const TAU = Math.PI * 2;
 /** Przerwa u dołu — kąt „otwarcia" łuku, żeby początek i koniec były rozróżnialne. */
 const GAP = Math.PI / 4;
@@ -13,7 +14,8 @@ const SWEEP = TAU - GAP * 2;
  * @example
  * <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
  */
-export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max = 100, step = 1, size = 96, stroke = 10, suffix = '', showValue = true, disabled = false, invalid = false, touched, onTouch, className, ...rest }) {
+export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max = 100, step = 1, size = 96, stroke = 10, suffix = '', showValue = true, id, ariaLabel = null, disabled = false, invalid = false, touched, onTouch, className, ...rest }) {
+    const field = useKptFieldA11y(id, 'kpt-knob');
     const svgRef = useRef(null);
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const showInvalid = invalid && (touched ?? true);
@@ -82,5 +84,5 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
         setCurrent(Math.min(max, Math.max(min, next)));
         onTouch?.();
     };
-    return (_jsx("div", { className: cn('kpt-knob-host', className), ...rest, children: _jsx("div", { className: cn('kpt-knob', showInvalid && 'kpt-knob--invalid'), role: "slider", tabIndex: disabled ? -1 : 0, "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": current, "aria-disabled": disabled || undefined, onPointerDown: onPointerDown, onKeyDown: onKeyDown, children: _jsxs("svg", { ref: svgRef, viewBox: `0 0 ${size} ${size}`, style: { width: size, height: size }, children: [_jsx("path", { className: "kpt-knob__range", d: arc(0, 1), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), _jsx("path", { className: "kpt-knob__value", d: arc(0, ratio), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), showValue ? (_jsxs("text", { className: "kpt-knob__text", x: size / 2, y: size / 2, textAnchor: "middle", dominantBaseline: "central", children: [current, suffix] })) : null] }) }) }));
+    return (_jsx("div", { className: cn('kpt-knob-host', className), ...rest, children: _jsx("div", { className: cn('kpt-knob', showInvalid && 'kpt-knob--invalid'), role: "slider", id: field.id, tabIndex: disabled ? -1 : 0, "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": current, "aria-valuetext": suffix ? `${current}${suffix}` : undefined, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onPointerDown: onPointerDown, onKeyDown: onKeyDown, children: _jsxs("svg", { ref: svgRef, viewBox: `0 0 ${size} ${size}`, style: { width: size, height: size }, children: [_jsx("path", { className: "kpt-knob__range", d: arc(0, 1), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), _jsx("path", { className: "kpt-knob__value", d: arc(0, ratio), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), showValue ? (_jsxs("text", { className: "kpt-knob__text", x: size / 2, y: size / 2, textAnchor: "middle", dominantBaseline: "central", children: [current, suffix] })) : null] }) }) }));
 }

package/dist/knob/llms.txt

@@ -36,6 +36,14 @@ on `pointerup`, which is also where `onTouch` fires — one touch per drag, not
     <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
     <KptKnob value={level} onValueChange={setLevel} size={64} stroke={6} showValue={false} />
 
+## Label and description
+`id` goes to the focusable element, not the host; without one it comes from `KptFormField` or is
+generated. A `div` with a role is not named by `label[for]`, so inside `KptFormField` it gets
+`aria-labelledby` pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error
+is added to `aria-describedby`. New: `id`, `ariaLabel`; `aria-valuetext` includes `suffix` ("40%"),
+and a disabled knob leaves the Tab order. Use `ariaLabel`, not `aria-label` on the host — that one
+lands on the wrapper.
+
 ## Tokens
 The background arc `--kpt-color-border`, the value `--kpt-color-primary`, the text
 `--kpt-color-on-surface`.