@konce-pt/react 0.9.1 → 0.11.0

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;
@@ -21,7 +25,11 @@ export interface KptKnobProps extends Omit<ComponentPropsWithRef<'div'>, 'onChan
 /**
  * Pokrętło — wybór wartości po łuku, przeciąganiem albo strzałkami.
  *
+ * Skok wartości (strzałka, `Home`/`End`, klik w łuk, zmiana z zewnątrz) łuk i licznik pokonują
+ * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `prefers-reduced-motion` wyłącza
+ * animację, a `aria-valuenow` zawsze niesie wartość docelową, nie pośrednią.
+ *
  * @example
  * <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
  */
-export declare function KptKnob({ value, defaultValue, onValueChange, min, max, step, size, stroke, suffix, showValue, 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

@@ -1,24 +1,49 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
+import { kptStepDecimals, kptTween } from "../internal/tween.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;
 const START_ANGLE = Math.PI / 2 + GAP;
 const SWEEP = TAU - GAP * 2;
+/** Czas dojścia łuku i licznika po skoku wartości (klawisz, klik, zmiana z zewnątrz). */
+const TWEEN_MS = 220;
 /**
  * Pokrętło — wybór wartości po łuku, przeciąganiem albo strzałkami.
  *
+ * Skok wartości (strzałka, `Home`/`End`, klik w łuk, zmiana z zewnątrz) łuk i licznik pokonują
+ * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `prefers-reduced-motion` wyłącza
+ * animację, a `aria-valuenow` zawsze niesie wartość docelową, nie pośrednią.
+ *
  * @example
  * <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
  */
-export 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);
     const range = max - min;
-    const ratio = range <= 0 ? 0 : (current - min) / range;
+    /** Wartość na rysunku — w trakcie animacji pośrednia, poza nią równa `current`. */
+    const [shown, setShown] = useState(current);
+    const shownRef = useRef(current);
+    /** Przeciąganie trwa — wtedy rysunek idzie za kursorem bez animacji. */
+    const dragging = useRef(false);
+    useEffect(() => {
+        const paint = (v) => {
+            shownRef.current = v;
+            setShown(v);
+        };
+        if (dragging.current) {
+            paint(current);
+            return;
+        }
+        return kptTween(shownRef.current, current, TWEEN_MS, paint);
+    }, [current]);
+    const ratio = range <= 0 ? 0 : Math.min(1, Math.max(0, (shown - min) / range));
     /** Wycinek łuku jako ścieżka SVG; `to <= from` daje samo `M`, czyli nic widocznego. */
     const arc = (from, to) => {
         const r = (size - stroke) / 2;
@@ -52,17 +77,28 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
     const onPointerDown = (event) => {
         if (disabled)
             return;
+        // Bez tego przeciąganie zaznacza tekst: licznik w środku i — przez SVG — całe koło, jak po
+        // `Ctrl+A`. Zablokowanie domyślnej akcji zabiera też fokus, więc oddajemy go ręcznie.
+        event.preventDefault();
+        event.currentTarget.focus();
+        // Klik w łuk to skok — animowany. Dopiero ruch po nim jest przeciąganiem.
         setFromPoint(event.clientX, event.clientY);
         // Nasłuch wisi na oknie, a nie na pokrętle: przeciąganie ma nie gubić wartości,
         // gdy kursor wyjedzie poza koło — a wyjeżdża praktycznie zawsze.
-        const move = (e) => setFromPoint(e.clientX, e.clientY);
+        const move = (e) => {
+            dragging.current = true;
+            setFromPoint(e.clientX, e.clientY);
+        };
         const up = () => {
             window.removeEventListener('pointermove', move);
             window.removeEventListener('pointerup', up);
+            window.removeEventListener('pointercancel', up);
+            dragging.current = false;
             onTouch?.();
         };
         window.addEventListener('pointermove', move);
         window.addEventListener('pointerup', up);
+        window.addEventListener('pointercancel', up);
     };
     const onKeyDown = (event) => {
         if (disabled)
@@ -82,5 +118,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: [shown.toFixed(kptStepDecimals(step)), suffix] })) : null] }) }) }));
 }

package/dist/knob/llms.txt

@@ -36,10 +36,25 @@ 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`.
 
+## Motion
+A jump in value — an arrow key, Home/End, a click on the arc, a change from outside — moves the arc
+and counts the number up or down over ~220 ms (ease-out). Dragging follows the pointer with no
+delay, so it never feels laggy. `prefers-reduced-motion: reduce` turns the animation off.
+`aria-valuenow` always carries the target value, never an in-between frame. Dragging does not
+select the number or the arc.
+
 ## Accessibility
 `role="slider"` with `aria-valuemin` / `aria-valuemax` / `aria-valuenow`; arrows step by `step`,
 Home and End jump to the bounds. `disabled` sets `aria-disabled` and drops the knob out of the

package/dist/listbox/listbox.d.ts

@@ -9,6 +9,12 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
     multiple?: boolean;
     /** Pole filtrowania nad listą. */
     filter?: boolean;
+    /** Id listy (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
+    /** Nazwa dostępna listy, gdy nie opisuje jej etykieta (`KptFormField`). */
+    ariaLabel?: string | null;
+    /** Oznacza listę jako wymaganą atrybutem `aria-required`. */
+    required?: boolean;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -21,8 +27,14 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
  * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją — lista bywa filtrem,
  * a filtr trzeba dać się wyczyścić bez sięgania po osobny przycisk.
  *
+ * Klawiatura według wzorca WAI-ARIA „listbox”: lista to jeden przystanek Tab, a aktywną opcję
+ * ogłasza `aria-activedescendant`. Strzałki, `Home`/`End`, `PageUp`/`PageDown` przesuwają aktywną
+ * opcję (wyłączone są pomijane), pisanie liter skacze do kolejnej pasującej (bez względu na
+ * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`⌘`+`A` zaznacza wszystkie
+ * widoczne. Pole filtra stoi przed listą; `↓` przenosi z niego fokus do listy.
+ *
  * @example
  * <KptListbox options={roles} value={role} onValueChange={setRole} filter />
  * <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
  */
-export declare function KptListbox<T>({ options, value, defaultValue, onValueChange, multiple, filter, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptListboxProps<T>>): import("react").JSX.Element;
+export declare function KptListbox<T>({ options, value, defaultValue, onValueChange, multiple, filter, id, ariaLabel, required, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptListboxProps<T>>): import("react").JSX.Element;

package/dist/listbox/listbox.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { foldMentionText } from '@konce-pt/mention';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { KptTypeahead, OPTION_NAV_KEYS, isTypeaheadKey, nextOptionIndex, typeaheadIndex } from "../internal/option-nav.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
 import { KptIcon } from "../icon/icon.js";
 /**
  * Lista wyboru widoczna w całości, bez rozwijania. Pojedynczy albo wielokrotny wybór,
@@ -11,23 +14,44 @@ import { KptIcon } from "../icon/icon.js";
  * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją — lista bywa filtrem,
  * a filtr trzeba dać się wyczyścić bez sięgania po osobny przycisk.
  *
+ * Klawiatura według wzorca WAI-ARIA „listbox”: lista to jeden przystanek Tab, a aktywną opcję
+ * ogłasza `aria-activedescendant`. Strzałki, `Home`/`End`, `PageUp`/`PageDown` przesuwają aktywną
+ * opcję (wyłączone są pomijane), pisanie liter skacze do kolejnej pasującej (bez względu na
+ * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`⌘`+`A` zaznacza wszystkie
+ * widoczne. Pole filtra stoi przed listą; `↓` przenosi z niego fokus do listy.
+ *
  * @example
  * <KptListbox options={roles} value={role} onValueChange={setRole} filter />
  * <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
  */
-export function KptListbox({ options = [], value, defaultValue = null, onValueChange, multiple = false, filter = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptListbox({ options = [], value, defaultValue = null, onValueChange, multiple = false, filter = false, id, ariaLabel = null, required = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
+    /** `div` z rolą nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
+    const field = useKptFieldA11y(id, 'kpt-listbox');
     const [current, setCurrent] = useControllableState({
         value,
         defaultValue,
         onChange: onValueChange,
     });
     const [query, setQuery] = useState('');
+    /** Aktywna opcja (indeks w `visible`); `-1` = żadna. */
+    const [activeIndex, setActiveIndex] = useState(-1);
+    const listRef = useRef(null);
+    const typeahead = useRef(new KptTypeahead()).current;
     const showInvalid = invalid && (touched ?? true);
+    /** Filtr bez względu na wielkość liter i diakrytyki („lodz” znajduje „Łódź”). */
     const visible = useMemo(() => {
-        const q = query.trim().toLowerCase();
-        return q ? options.filter((option) => option.label.toLowerCase().includes(q)) : options;
+        const q = foldMentionText(query.trim());
+        return q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
     }, [options, query]);
+    const disabledMap = visible.map((option) => disabled || !!option.disabled);
+    const optionId = (index) => `${field.id}-opt-${index}`;
+    const activeOptionId = activeIndex >= 0 && activeIndex < visible.length ? optionId(activeIndex) : undefined;
+    // Aktywna opcja zawsze w polu widzenia listy (przewijana `max-height`).
+    useEffect(() => {
+        if (activeOptionId)
+            document.getElementById(activeOptionId)?.scrollIntoView({ block: 'nearest' });
+    }, [activeOptionId]);
     const isSelected = (candidate) => multiple ? Array.isArray(current) && current.includes(candidate) : current === candidate;
     const toggle = (candidate) => {
         if (multiple) {
@@ -37,7 +61,66 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
         else {
             setCurrent(current === candidate ? null : candidate);
         }
-        onTouch?.();
     };
-    return (_jsx("div", { className: cn('kpt-listbox-host', className), ...rest, children: _jsxs("div", { className: cn('kpt-listbox', showInvalid && 'kpt-listbox--invalid'), role: "listbox", "aria-multiselectable": multiple, children: [filter ? (_jsxs("div", { className: "kpt-listbox__filter", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { type: "text", placeholder: t('listbox.search'), value: query, onChange: (event) => setQuery(event.target.value) })] })) : null, _jsx("div", { className: "kpt-listbox__items", children: visible.length ? (visible.map((option) => (_jsxs("button", { type: "button", role: "option", className: cn('kpt-listbox__item', isSelected(option.value) && 'is-selected'), "aria-selected": isSelected(option.value), disabled: disabled || option.disabled, onClick: () => toggle(option.value), children: [_jsx("span", { children: option.label }), isSelected(option.value) ? _jsx(KptIcon, { name: "check" }) : null] }, String(option.value))))) : (_jsx("div", { className: "kpt-listbox__empty", children: t('listbox.empty') })) })] }) }));
+    const pick = (index) => {
+        const option = visible[index];
+        if (!option || disabledMap[index])
+            return;
+        setActiveIndex(index);
+        toggle(option.value);
+    };
+    /** Wejście fokusem: aktywna zostaje wybrana opcja, a bez niej pierwsza dozwolona. */
+    const onFocus = () => {
+        if (activeIndex >= 0 && activeIndex < visible.length)
+            return;
+        const selected = visible.findIndex((option, index) => isSelected(option.value) && !disabledMap[index]);
+        setActiveIndex(selected >= 0 ? selected : (nextOptionIndex(disabledMap, -1, 'Home') ?? -1));
+    };
+    const onQuery = (text) => {
+        setQuery(text);
+        const q = foldMentionText(text.trim());
+        const next = q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
+        setActiveIndex(nextOptionIndex(next.map((option) => disabled || !!option.disabled), -1, 'Home') ?? -1);
+    };
+    const onKeyDown = (event) => {
+        if (disabled)
+            return;
+        if (OPTION_NAV_KEYS.has(event.key)) {
+            event.preventDefault();
+            const next = nextOptionIndex(disabledMap, activeIndex, event.key);
+            if (next !== null)
+                setActiveIndex(next);
+            return;
+        }
+        if (event.key === ' ' || event.key === 'Enter') {
+            if (activeIndex < 0)
+                return;
+            event.preventDefault();
+            pick(activeIndex);
+            return;
+        }
+        if (multiple && (event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'a') {
+            event.preventDefault();
+            const all = visible.filter((_, index) => !disabledMap[index]).map((option) => option.value);
+            const list = Array.isArray(current) ? current : [];
+            // Drugi raz `Ctrl+A` przy wszystkich zaznaczonych — odznacza widoczne.
+            const allOn = all.every((item) => list.includes(item));
+            setCurrent(allOn ? list.filter((item) => !all.includes(item)) : [...list, ...all.filter((item) => !list.includes(item))]);
+            return;
+        }
+        if (isTypeaheadKey(event.nativeEvent)) {
+            const hit = typeaheadIndex(visible.map((option) => option.label), disabledMap, activeIndex, typeahead.push(event.key));
+            if (hit !== null)
+                setActiveIndex(hit);
+        }
+    };
+    return (_jsx("div", { className: cn('kpt-listbox-host', className), ...rest, children: _jsxs("div", { className: cn('kpt-listbox', showInvalid && 'kpt-listbox--invalid', disabled && 'kpt-listbox--disabled'), children: [filter ? (_jsxs("div", { className: "kpt-listbox__filter", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { type: "text", placeholder: t('listbox.search'), "aria-label": t('listbox.search'), "aria-controls": field.id, disabled: disabled, value: query, onChange: (event) => onQuery(event.target.value), onKeyDown: (event) => {
+                                if (event.key !== 'ArrowDown')
+                                    return;
+                                event.preventDefault();
+                                listRef.current?.focus();
+                            } })] })) : null, _jsx("div", { ref: listRef, className: "kpt-listbox__items", role: "listbox", id: field.id, tabIndex: disabled ? -1 : 0, "aria-multiselectable": multiple || undefined, "aria-activedescendant": activeOptionId, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, "aria-required": required || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onKeyDown: onKeyDown, onFocus: onFocus, onBlur: () => onTouch?.(), children: visible.length ? (visible.map((option, index) => (_jsxs("div", { role: "option", id: optionId(index), className: cn('kpt-listbox__item', isSelected(option.value) && 'is-selected', index === activeIndex && 'is-active'), "aria-selected": isSelected(option.value), "aria-disabled": disabledMap[index] || undefined, onMouseDown: (event) => {
+                            event.preventDefault();
+                            listRef.current?.focus();
+                        }, onClick: () => pick(index), children: [_jsx("span", { children: option.label }), isSelected(option.value) ? _jsx(KptIcon, { name: "check" }) : null] }, String(option.value))))) : (_jsx("div", { className: "kpt-listbox__empty", role: "status", children: t('listbox.empty') })) })] }) }));
 }

package/dist/listbox/llms.txt

@@ -5,10 +5,10 @@ Import: `import { KptListbox } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-listbox-host">
-      <div class="kpt-listbox" role="listbox" aria-multiselectable="false">
+      <div class="kpt-listbox">
         <div class="kpt-listbox__filter">…icon + input…</div>
-        <div class="kpt-listbox__items">
-          <button class="kpt-listbox__item is-selected" role="option" aria-selected="true">Admin</button>
+        <div class="kpt-listbox__items" role="listbox" tabindex="0" aria-activedescendant="…-opt-0">
+          <div class="kpt-listbox__item is-selected is-active" role="option" id="…-opt-0" aria-selected="true">Admin</div>
         </div>
       </div>
     </div>
@@ -17,6 +17,7 @@ Import: `import { KptListbox } from '@konce-pt/react';`
 - `options`: `KptOption<T>[]`
 - `value` / `defaultValue` / `onValueChange` — `T` (single) or `T[]` (multiple)
 - `multiple`, `filter`, `disabled`, `invalid`, `touched`, `onTouch()`
+- `id`, `ariaLabel`, `required`
 - `locale`, `dictionary` — i18n overrides for this component only
 
 ## Clicking the selection clears it
@@ -30,10 +31,25 @@ filter has to be clearable without a separate button.
     <KptListbox options={roles} value={role} onValueChange={setRole} filter />
     <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
 
+## Keyboard
+The WAI-ARIA listbox pattern: the list is one Tab stop and the active option is announced through
+`aria-activedescendant`. `↑`/`↓`, `Home`/`End` and `PageUp`/`PageDown` move the active option,
+skipping disabled ones (no wrapping); typing letters jumps to the next match, diacritics ignored;
+`Space`/`Enter` picks; in `multiple` mode `Ctrl`/`⌘`+`A` selects every visible option (again —
+clears them). The filter field sits before the list (outside the `listbox`) and `↓` moves focus
+from it into the list; the filter itself ignores diacritics ("lodz" finds "Łódź").
+
+## Label and description
+`id` goes to the list (`role="listbox"`), never the host. A `div` with a role is not named by
+`label[for]`, so inside `KptFormField` the list gets `aria-labelledby` pointing at the wrapper's
+label (unless `ariaLabel` is set) and the hint or error in `aria-describedby`. New: `id`,
+`ariaLabel`, `required` (→ `aria-required`); `aria-invalid` after touch; `touch` fires on blur of the list.
+
 ## Tokens
 `--kpt-color-surface`, `--kpt-color-border`, `--kpt-color-primary-subtle` (the selected row),
 `--kpt-form-field-border-error`.
 
 ## Accessibility
-`role="listbox"` with `aria-multiselectable`; every option is a native button with
-`role="option"` and `aria-selected`, so the keyboard walks the list without extra handling.
+The list is `role="listbox"` with `aria-multiselectable`, `aria-activedescendant` and a name from
+`ariaLabel` or `KptFormField`; options are `role="option"` with `aria-selected`/`aria-disabled`.
+The keyboard is described above.

package/dist/megamenu/llms.txt

@@ -5,21 +5,23 @@ Import: `import { KptMegamenu } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-megamenu-host">
-      <nav class="kpt-megamenu" role="menubar">
-        <button class="kpt-megamenu__top is-open" role="menuitem">Products …caret…</button>
-      </nav>
+      <div class="kpt-megamenu" role="menubar" aria-orientation="horizontal" aria-label="Main menu">
+        <button class="kpt-megamenu__top is-open" role="menuitem" tabindex="0"
+                aria-haspopup="menu" aria-expanded="true" aria-controls="kpt-megamenu-r1">Products …caret…</button>
+      </div>
     </div>
     <!-- while open, in a portal: -->
-    <div class="kpt-megamenu__panel" role="menu">
-      <div class="kpt-megamenu__column">
-        <div class="kpt-megamenu__col-title">Components</div>
-        <button class="kpt-megamenu__link">Forms</button>
+    <div class="kpt-megamenu__panel" role="menu" id="kpt-megamenu-r1" aria-label="Products">
+      <div class="kpt-megamenu__column" role="group" aria-labelledby="kpt-megamenu-r1-col-0">
+        <div class="kpt-megamenu__col-title" role="presentation" id="kpt-megamenu-r1-col-0">Components</div>
+        <button class="kpt-megamenu__link" role="menuitem" tabindex="-1">Forms</button>
       </div>
     </div>
 
 ## Props
 - `items`: `KptMenuItem<T>[]` — three levels: top item → `items` (columns) → column `items` (links)
-- `onSelect(link)` — a picked link from a column
+- `onSelect(link)` — a picked link from a column, or a top item without columns
+- `ariaLabel`: string — the bar's name for screen readers, e.g. "Main menu"
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The panel is anchored to the whole bar
@@ -39,10 +41,26 @@ without closing the panel, so browsing across sections costs one click each.
       ],
     }];
 
+## Links (`url`)
+An entry with `url` and no children (and not disabled) renders as a real `<a href>` with the same
+look, so the browser handles navigation — opening in a new tab, the status-bar preview. `onSelect`
+still fires before the browser follows the link.
+
 ## Tokens
 `--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-elevation-3`,
 `--kpt-color-on-surface-muted` (the column titles).
 
 ## Accessibility
-The bar is `role="menubar"` with `role="menuitem"` buttons; the panel is `role="menu"`. Column
-titles are plain text, not headings, so they do not disturb the page outline.
+The bar is `role="menubar"` (`aria-orientation="horizontal"`, named by `ariaLabel`) with
+`role="menuitem"` buttons; those with columns carry `aria-haspopup="menu"`, `aria-expanded` and
+`aria-controls`. The panel is `role="menu"` named after the open item, each column is
+`role="group"` named by its title, and links are `role="menuitem"`. Column titles are not headings,
+so they do not disturb the page outline. A top item without columns fires `onSelect` instead of
+opening an empty panel.
+
+## Keyboard
+The same as `KptMenubar`: one `Tab` stop for the bar, `ArrowLeft`/`ArrowRight` and `Home`/`End`
+along it, `ArrowDown` (or `Enter`/`Space`) opens the panel on the first link, `ArrowUp` on the last.
+In the panel `ArrowDown`/`ArrowUp`/`Home`/`End` walk through all links column by column,
+`ArrowLeft`/`ArrowRight` show the neighbouring item's panel, `Escape` or `Tab` close it and return
+focus to the top item.

package/dist/megamenu/megamenu.d.ts

@@ -3,15 +3,24 @@ import type { KptMenuItem } from '../menu/menu-item.ts';
 export interface KptMegamenuProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect'> {
     items?: readonly KptMenuItem<T>[];
     onSelect?: (item: KptMenuItem<T>) => void;
+    /** Nazwa belki dla czytników ekranu, np. „Menu główne”. */
+    ariaLabel?: string;
 }
 /**
  * Mega-menu — pozioma belka z szerokim, wielokolumnowym panelem.
  * Struktura: pozycja górna → `items` (kolumny) → `items` kolumny (odnośniki).
+ * Pozycja górna bez kolumn działa jak akcja — wywołuje `onSelect` zamiast otwierać pusty panel.
  *
  * Panel kotwiczy się do CAŁEJ belki, nie do pojedynczego przycisku: jest szeroki, więc ma
  * zaczynać się przy krawędzi menu, a nie przy przypadkowej pozycji, w którą kliknięto.
  *
+ * Klawiatura jak w `KptMenubar`: belka to jeden przystanek Tab, strzałki w lewo/prawo
+ * i `Home`/`End` chodzą po pozycjach górnych, strzałka w dół (albo `Enter`/spacja) otwiera panel
+ * z fokusem na pierwszym odnośniku. W panelu strzałki w górę/dół przechodzą po wszystkich
+ * odnośnikach kolumna po kolumnie, w lewo/prawo — do panelu sąsiedniej pozycji, a `Escape`
+ * zamyka panel i oddaje fokus belce.
+ *
  * @example
  * <KptMegamenu items={items} onSelect={onSelect} />
  */
-export declare function KptMegamenu<T>({ items, onSelect, className, ...rest }: Readonly<KptMegamenuProps<T>>): import("react").JSX.Element;
+export declare function KptMegamenu<T>({ items, onSelect, ariaLabel, className, ...rest }: Readonly<KptMegamenuProps<T>>): import("react").JSX.Element;