@konce-pt/react 0.9.1 → 0.10.0

package/dist/datepicker/datepicker.d.ts

@@ -23,6 +23,8 @@ export interface KptDatepickerProps extends Omit<ComponentPropsWithRef<'div'>, '
     onOpenChange?: (open: boolean) => void;
     /** Nazwa dostępna, gdy pola nie opisuje `<label for>`. */
     ariaLabel?: string | null;
+    /** Id pola (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -32,8 +34,15 @@ export interface KptDatepickerProps extends Omit<ComponentPropsWithRef<'div'>, '
  * Wybór daty i godziny z własnym kalendarzem. Panel jest stosem widoków
  * dekady → lata → miesiące → dni: klik w komórkę schodzi poziom niżej, klik w tytuł wchodzi wyżej.
  *
+ * Klawiatura według wzorca WAI-ARIA „date picker dialog”: `Enter`/`Spacja`/`↓` na polu otwierają
+ * kalendarz i przenoszą fokus na wybrany (albo dzisiejszy) dzień. W siatce dni strzałki chodzą
+ * o dzień i tydzień, `Home`/`End` na początek i koniec tygodnia, `PageUp`/`PageDown` o miesiąc
+ * (z `Shift` — o rok); w siatkach miesięcy, lat i dekad strzałki chodzą po komórkach. `Tab` krąży
+ * w panelu, `Escape` zamyka go, a wybór i zamknięcie oddają fokus polu. `Delete`/`Backspace` na polu
+ * czyści wartość.
+ *
  * @example
  * <KptDatepicker value={date} onValueChange={setDate} startView="decade" minDate="1920-01-01" />
  * <KptDatepicker selectionMode="datetime" hourFormat={12} value={at} onValueChange={setAt} />
  */
-export declare function KptDatepicker({ value, defaultValue, onValueChange, selectionMode, startView, minDate, maxDate, placeholder, monthDisplay, displayFormat, hourFormat, minuteStep, open, onOpenChange, ariaLabel, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptDatepickerProps>): import("react").JSX.Element;
+export declare function KptDatepicker({ value, defaultValue, onValueChange, selectionMode, startView, minDate, maxDate, placeholder, monthDisplay, displayFormat, hourFormat, minuteStep, open, onOpenChange, ariaLabel, id, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptDatepickerProps>): import("react").JSX.Element;

package/dist/datepicker/datepicker.js

@@ -1,26 +1,36 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
-import { KPT_CALENDAR_LEVELS, buildDayGrid, buildDecadeCells, buildMonthCells, buildYearCells, canPageBack, canPageForward, centuryStart, commitLevelFor, decadeStart, formatDate, formatTime, initialPage, pad, pageBy, parseDateTime, parseTime, resolveStartView, selectedYearMonth, toIso, } from '@konce-pt/datetime';
+import { useEffect, useRef, useState, } from 'react';
+import { KPT_CALENDAR_LEVELS, buildDayGrid, buildDecadeCells, buildMonthCells, buildYearCells, canPageBack, canPageForward, centuryStart, commitLevelFor, decadeStart, formatDate, formatTime, initialFocusDate, initialPage, moveCellIndex, moveFocusDate, pad, pageBy, parseDate, parseDateTime, parseTime, resolveStartView, selectedYearMonth, toIso, } from '@konce-pt/datetime';
 import { monthNames, weekdayNames } from '@konce-pt/i18n';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
-import { useKptFormFieldContext } from "../form-field/form-field-context.js";
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
 import { KptButton } from "../button/button.js";
 import { KptIcon } from "../icon/icon.js";
 import { KptClock } from "../clock/clock.js";
+import { useKptId } from "../internal/use-id.js";
+import { focusCalendarActive, trapTab } from "../internal/calendar-focus.js";
 /**
  * Wybór daty i godziny z własnym kalendarzem. Panel jest stosem widoków
  * dekady → lata → miesiące → dni: klik w komórkę schodzi poziom niżej, klik w tytuł wchodzi wyżej.
  *
+ * Klawiatura według wzorca WAI-ARIA „date picker dialog”: `Enter`/`Spacja`/`↓` na polu otwierają
+ * kalendarz i przenoszą fokus na wybrany (albo dzisiejszy) dzień. W siatce dni strzałki chodzą
+ * o dzień i tydzień, `Home`/`End` na początek i koniec tygodnia, `PageUp`/`PageDown` o miesiąc
+ * (z `Shift` — o rok); w siatkach miesięcy, lat i dekad strzałki chodzą po komórkach. `Tab` krąży
+ * w panelu, `Escape` zamyka go, a wybór i zamknięcie oddają fokus polu. `Delete`/`Backspace` na polu
+ * czyści wartość.
+ *
  * @example
  * <KptDatepicker value={date} onValueChange={setDate} startView="decade" minDate="1920-01-01" />
  * <KptDatepicker selectionMode="datetime" hourFormat={12} value={at} onValueChange={setAt} />
  */
-export function KptDatepicker({ value, defaultValue = '', onValueChange, selectionMode = 'date', startView = null, minDate = null, maxDate = null, placeholder = '', monthDisplay = 'long', displayFormat = 'pl', hourFormat = 24, minuteStep = 1, open, onOpenChange, ariaLabel = null, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptDatepicker({ value, defaultValue = '', onValueChange, selectionMode = 'date', startView = null, minDate = null, maxDate = null, placeholder = '', monthDisplay = 'long', displayFormat = 'pl', hourFormat = 24, minuteStep = 1, open, onOpenChange, ariaLabel = null, id, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
     const { t, locale: activeLocale } = useKptMessages({ locale, dictionary });
-    const field = useKptFormFieldContext();
+    /** `div` z rolą nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
+    const field = useKptFieldA11y(id, 'kpt-datepicker');
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const [isOpen, setOpen] = useControllableState({ value: open, defaultValue: false, onChange: onOpenChange });
     const [anchor, setAnchor] = useState(null);
@@ -33,6 +43,14 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
     const [timeStr, setTimeStr] = useState('');
     const [pendingDate, setPendingDate] = useState('');
     const [dtView, setDtView] = useState('calendar');
+    /** Dzień z fokusem w siatce dni — jedyny przystanek Tab siatki (roving tabindex). */
+    const [focusIso, setFocusIso] = useState('');
+    /** Komórka z fokusem w siatkach miesięcy, lat i dekad. */
+    const [focusCell, setFocusCell] = useState(0);
+    const panelId = useKptId(undefined, 'kpt-datepicker-panel');
+    const panelRef = useRef(null);
+    /** Prośba o przeniesienie fokusu po najbliższym renderze (otwarcie, ruch klawiszem, zmiana poziomu). */
+    const wantFocus = useRef(false);
     const months = monthNames(activeLocale);
     const weekdays = weekdayNames(activeLocale);
     const commitLevel = commitLevelFor(selectionMode);
@@ -53,6 +71,16 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
             setTimeStr(parsed ? `${pad(parsed.h)}:${pad(parsed.m)}` : '00:00');
             setPendingDate(parsed?.date ?? '');
         }
+        const startLevel = resolveStartView(selectionMode, startView);
+        const selected = selectionMode === 'datetime' ? (parseDateTime(current)?.date ?? '') : current;
+        const focus = initialFocusDate(selected, todayIso, minDate, maxDate);
+        setFocusIso(focus);
+        if (startLevel === 'day' && selectionMode !== 'time') {
+            const date = parseDate(focus);
+            setPage({ y: date.getFullYear(), m: date.getMonth() });
+        }
+        setFocusCell(-1); // -1 = domyślna komórka nowej siatki, wyliczana przy renderze
+        wantFocus.current = true;
         // Zależność wyłącznie od `isOpen`: to otwarcie ma ustawić stan początkowy, a późniejsze
         // zmiany wartości w otwartym panelu nie mogą go zresetować pod palcami użytkownika.
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -66,6 +94,21 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
         setOpen(false);
         onTouch?.();
     };
+    /** Zamknięcie z powrotem fokusu na pole — po wyborze z klawiatury, `Escape`. */
+    const closeAndFocus = () => {
+        close();
+        triggerRef.current?.focus();
+    };
+    // Fokus po renderze. Panel w nakładce jest niewidoczny do pierwszego pomiaru — stąd rAF.
+    useEffect(() => {
+        if (!isOpen || !wantFocus.current)
+            return;
+        const frame = requestAnimationFrame(() => {
+            wantFocus.current = false;
+            focusCalendarActive(panelRef.current, focusIso);
+        });
+        return () => cancelAnimationFrame(frame);
+    });
     // ── Prezentacja w triggerze ──
     const effectivePlaceholder = (() => {
         if (placeholder)
@@ -140,6 +183,65 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
                 minDate,
                 maxDate,
             });
+    const defaultCell = (() => {
+        const pick = levelCells.findIndex((c) => c.selected);
+        if (pick >= 0)
+            return pick;
+        const now = levelCells.findIndex((c) => c.current && !c.disabled);
+        return now >= 0 ? now : Math.max(0, levelCells.findIndex((c) => !c.disabled));
+    })();
+    const activeCell = focusCell >= 0 && focusCell < levelCells.length ? focusCell : defaultCell;
+    /** Pełna nazwa dnia dla czytnika („czwartek, 8 października 2026”) — sama liczba nic nie mówi. */
+    const dayFormat = new Intl.DateTimeFormat(activeLocale, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
+    const dayName = (iso) => {
+        const date = parseDate(iso);
+        return date ? dayFormat.format(date) : iso;
+    };
+    const isRtl = () => !!panelRef.current && getComputedStyle(panelRef.current).direction === 'rtl';
+    const onDayKeyDown = (event) => {
+        const next = moveFocusDate(focusIso, event.key, { shift: event.shiftKey, rtl: isRtl(), minDate, maxDate });
+        if (next === null)
+            return;
+        event.preventDefault();
+        setFocusIso(next);
+        const date = parseDate(next);
+        if (date.getFullYear() !== page.y || date.getMonth() !== page.m)
+            setPage({ y: date.getFullYear(), m: date.getMonth() });
+        wantFocus.current = true;
+    };
+    const onCellKeyDown = (event) => {
+        const next = moveCellIndex(levelCells.map((c) => c.disabled), activeCell, event.key, 3, isRtl());
+        if (next === null)
+            return;
+        event.preventDefault();
+        setFocusCell(next);
+        wantFocus.current = true;
+    };
+    /** Tytuł, który kliknięto, znika razem z poziomem — fokus idzie do nowej siatki. */
+    const goTo = (level) => {
+        setPanelView(level);
+        setFocusCell(-1);
+        wantFocus.current = true;
+    };
+    /** Strzałki ‹ ›: fokus zostaje na strzałce, ale przystanek siatki dni idzie za stroną. */
+    const turnPage = (dir) => {
+        const next = pageBy(page, panelView, dir);
+        setPage(next);
+        if (panelView === 'day') {
+            const moved = moveFocusDate(focusIso, dir === 1 ? 'PageDown' : 'PageUp', { minDate, maxDate });
+            // Dzień przycięty do granicy może leżeć poza nową stroną — wtedy pierwszy dozwolony dzień miesiąca.
+            const inPage = moved?.startsWith(`${next.y}-${pad(next.m + 1)}`);
+            const fallback = buildDayGrid({ page: next, selectedIso: selectedDateIso, todayIso, minDate, maxDate })
+                .flat()
+                .find((c) => c.inMonth && !c.disabled)?.iso;
+            const target = inPage ? moved : fallback;
+            if (target)
+                setFocusIso(target);
+        }
+        else {
+            setFocusCell(-1);
+        }
+    };
     const navLabel = (dir) => {
         switch (panelView) {
             case 'month':
@@ -161,7 +263,7 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
             return;
         }
         setCurrent(iso);
-        close();
+        closeAndFocus();
     };
     const selectCell = (cell) => {
         if (cell.disabled)
@@ -169,11 +271,22 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
         if (panelView === commitLevel) {
             const mm = pad(cell.m + 1);
             setCurrent(panelView === 'year' ? String(cell.y) : selectionMode === 'month' ? mm : `${cell.y}-${mm}`);
-            close();
+            closeAndFocus();
             return;
         }
-        setPage(({ m }) => ({ y: cell.y, m: panelView === 'month' ? cell.m : m }));
-        setPanelView(KPT_CALENDAR_LEVELS[KPT_CALENDAR_LEVELS.indexOf(panelView) - 1]);
+        const m = panelView === 'month' ? cell.m : page.m;
+        setPage({ y: cell.y, m });
+        const lower = KPT_CALENDAR_LEVELS[KPT_CALENDAR_LEVELS.indexOf(panelView) - 1];
+        setPanelView(lower);
+        // Zejście poziom niżej: fokus na pierwszą sensowną komórkę nowej siatki (albo dzień miesiąca).
+        if (lower === 'day') {
+            const day = Math.min(parseDate(focusIso)?.getDate() ?? 1, new Date(cell.y, m + 1, 0).getDate());
+            setFocusIso(initialFocusDate(`${cell.y}-${pad(m + 1)}-${pad(day)}`, todayIso, minDate, maxDate));
+        }
+        else {
+            setFocusCell(-1);
+        }
+        wantFocus.current = true;
     };
     const commit = () => {
         const time = timeStr || '00:00';
@@ -184,7 +297,7 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
             const parsed = parseDateTime(current);
             setCurrent(`${pendingDate || parsed?.date || todayIso}T${time}`);
         }
-        close();
+        closeAndFocus();
     };
     const clear = (event) => {
         event.stopPropagation();
@@ -195,8 +308,28 @@ export function KptDatepicker({ value, defaultValue = '', onValueChange, selecti
     return (_jsxs("div", { className: cn('kpt-datepicker-host', className), ...rest, children: [_jsxs("div", { ref: (el) => {
                     triggerRef.current = el;
                     setAnchor(el);
-                }, className: cn('kpt-datepicker', isOpen && 'kpt-datepicker--open', disabled && 'kpt-datepicker--disabled', showInvalid && 'kpt-datepicker--invalid'), role: "button", tabIndex: 0, id: field?.controlId, "aria-disabled": disabled || undefined, "aria-label": ariaLabel ?? undefined, onClick: () => !disabled && setOpen(!isOpen), onKeyDown: (event) => {
-                    if (event.key === 'Enter' && !disabled)
-                        setOpen(!isOpen);
-                }, onBlur: () => onTouch?.(), children: [display ? (_jsx("span", { className: "kpt-datepicker__value", children: display })) : (_jsx("span", { className: "kpt-datepicker__placeholder", children: effectivePlaceholder })), _jsx("span", { className: "kpt-datepicker__spacer" }), display ? (_jsx("button", { type: "button", className: "kpt-datepicker__clear", onClick: clear, "aria-label": t('common.clear'), children: _jsx(KptIcon, { name: "x" }) })) : null, _jsx(KptIcon, { className: "kpt-datepicker__icon", name: selectionMode === 'time' ? 'clock' : 'calendar' })] }), _jsx(KptOverlay, { open: isOpen, anchor: anchor, onClose: close, offset: 4, children: _jsxs("div", { className: cn('kpt-calendar', showClock && 'kpt-calendar--clock'), children: [showClock ? (_jsxs(_Fragment, { children: [selectionMode === 'datetime' ? (_jsxs("div", { className: "kpt-calendar__header", children: [_jsx("button", { type: "button", className: "kpt-calendar__nav", onClick: () => setDtView('calendar'), "aria-label": t('datepicker.calendar'), children: _jsx(KptIcon, { name: "chevron-left" }) }), _jsx("span", { className: "kpt-calendar__title", children: t('datepicker.time') })] })) : null, _jsx(KptClock, { value: timeStr, onValueChange: setTimeStr, hourFormat: hourFormat, minuteStep: minuteStep })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-calendar__header", children: [hasNav ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", disabled: !canPageBack(page, panelView, minDate), onClick: () => setPage(pageBy(page, panelView, -1)), "aria-label": navLabel('prev'), children: _jsx(KptIcon, { name: "chevron-left" }) })) : null, _jsxs("span", { className: "kpt-calendar__titles", children: [panelView === 'day' ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => setPanelView('month'), "aria-label": t('datepicker.chooseMonth'), children: months[page.m] }), _jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => setPanelView('year'), "aria-label": t('datepicker.chooseYear'), children: page.y })] })) : null, panelView === 'month' ? (selectionMode === 'month' ? (_jsx("span", { className: "kpt-calendar__title", children: t('datepicker.month') })) : (_jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => setPanelView('year'), "aria-label": t('datepicker.chooseYear'), children: page.y }))) : null, panelView === 'year' ? (_jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => setPanelView('decade'), "aria-label": t('datepicker.chooseDecade'), children: `${decadeStart(page.y)} – ${decadeStart(page.y) + 9}` })) : null, panelView === 'decade' ? (_jsx("span", { className: "kpt-calendar__title", children: `${centuryStart(page.y)} – ${centuryStart(page.y) + 119}` })) : null] }), hasNav ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", disabled: !canPageForward(page, panelView, maxDate), onClick: () => setPage(pageBy(page, panelView, 1)), "aria-label": navLabel('next'), children: _jsx(KptIcon, { name: "chevron-right" }) })) : null] }), panelView === 'day' ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "kpt-calendar__weekdays", children: weekdays.map((weekday) => (_jsx("span", { className: "kpt-calendar__weekday", children: weekday }, weekday))) }), _jsx("div", { className: "kpt-calendar__grid", children: weeks.flat().map((cell) => (_jsx("button", { type: "button", className: cn('kpt-calendar__day', !cell.inMonth && 'kpt-calendar__day--muted', cell.today && 'kpt-calendar__day--today', cell.selected && 'kpt-calendar__day--selected'), disabled: cell.disabled, "aria-pressed": cell.selected, onClick: () => selectDay(cell.iso, cell.disabled), children: cell.day }, cell.iso))) })] })) : (_jsx("div", { className: cn('kpt-calendar__grid kpt-calendar__grid--cells', panelView === 'decade' && 'kpt-calendar__grid--decades'), children: levelCells.map((cell) => (_jsx("button", { type: "button", className: cn('kpt-calendar__cell', cell.selected && 'kpt-calendar__cell--selected', cell.current && 'kpt-calendar__cell--current'), disabled: cell.disabled, "aria-pressed": cell.selected, onClick: () => selectCell(cell), children: cell.label }, cell.label))) })), selectionMode === 'datetime' ? (_jsxs("button", { type: "button", className: "kpt-calendar__timebar", onClick: () => setDtView('clock'), children: [_jsx(KptIcon, { name: "clock" }), _jsx("span", { children: formatTime(timeParts?.h ?? 0, timeParts?.m ?? 0, hourFormat) })] })) : null] })), hasFooter ? (_jsx("div", { className: "kpt-calendar__footer", children: _jsx(KptButton, { size: "sm", onClick: commit, children: t('common.done') }) })) : null] }) })] }));
+                }, className: cn('kpt-datepicker', isOpen && 'kpt-datepicker--open', disabled && 'kpt-datepicker--disabled', showInvalid && 'kpt-datepicker--invalid'), role: "button", tabIndex: 0, "aria-haspopup": "dialog", "aria-expanded": isOpen, "aria-controls": isOpen ? panelId : undefined, id: field.id, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, "aria-disabled": disabled || undefined, "aria-label": ariaLabel ?? undefined, onClick: () => !disabled && setOpen(!isOpen), onKeyDown: (event) => {
+                    if (disabled)
+                        return;
+                    if (event.key === 'Enter' || event.key === ' ' || event.key === 'ArrowDown') {
+                        event.preventDefault();
+                        if (!isOpen)
+                            setOpen(true);
+                    }
+                    else if ((event.key === 'Delete' || event.key === 'Backspace') && current) {
+                        event.preventDefault();
+                        clear(event);
+                    }
+                }, 
+                // Przy otwartym panelu fokus idzie do kalendarza — „dotknięcie” wyśle dopiero zamknięcie.
+                onBlur: () => !isOpen && onTouch?.(), children: [display ? (_jsx("span", { className: "kpt-datepicker__value", children: display })) : (_jsx("span", { className: "kpt-datepicker__placeholder", children: effectivePlaceholder })), _jsx("span", { className: "kpt-datepicker__spacer" }), display ? (_jsx("button", { type: "button", className: "kpt-datepicker__clear", tabIndex: -1, onClick: clear, "aria-label": t('common.clear'), children: _jsx(KptIcon, { name: "x" }) })) : null, _jsx(KptIcon, { className: "kpt-datepicker__icon", name: selectionMode === 'time' ? 'clock' : 'calendar' })] }), _jsx(KptOverlay, { open: isOpen, anchor: anchor, onClose: close, offset: 4, children: _jsxs("div", { ref: panelRef, id: panelId, role: "dialog", "aria-label": t('datepicker.dialog'), className: cn('kpt-calendar', showClock && 'kpt-calendar--clock'), onKeyDown: (event) => {
+                        if (event.key === 'Escape') {
+                            event.preventDefault();
+                            event.stopPropagation();
+                            closeAndFocus();
+                        }
+                        else if (event.key === 'Tab') {
+                            trapTab(event.currentTarget, event.nativeEvent);
+                        }
+                    }, children: [showClock ? (_jsxs(_Fragment, { children: [selectionMode === 'datetime' ? (_jsxs("div", { className: "kpt-calendar__header", children: [_jsx("button", { type: "button", className: "kpt-calendar__nav", onClick: () => setDtView('calendar'), "aria-label": t('datepicker.calendar'), children: _jsx(KptIcon, { name: "chevron-left" }) }), _jsx("span", { className: "kpt-calendar__title", children: t('datepicker.time') })] })) : null, _jsx(KptClock, { value: timeStr, onValueChange: setTimeStr, hourFormat: hourFormat, minuteStep: minuteStep })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-calendar__header", children: [hasNav ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", disabled: !canPageBack(page, panelView, minDate), onClick: () => turnPage(-1), "aria-label": navLabel('prev'), children: _jsx(KptIcon, { name: "chevron-left" }) })) : null, _jsxs("span", { className: "kpt-calendar__titles", children: [panelView === 'day' ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => goTo('month'), "aria-label": t('datepicker.chooseMonth'), children: months[page.m] }), _jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => goTo('year'), "aria-label": t('datepicker.chooseYear'), children: page.y })] })) : null, panelView === 'month' ? (selectionMode === 'month' ? (_jsx("span", { className: "kpt-calendar__title", children: t('datepicker.month') })) : (_jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => goTo('year'), "aria-label": t('datepicker.chooseYear'), children: page.y }))) : null, panelView === 'year' ? (_jsx("button", { type: "button", className: "kpt-calendar__title-btn", onClick: () => goTo('decade'), "aria-label": t('datepicker.chooseDecade'), children: `${decadeStart(page.y)} – ${decadeStart(page.y) + 9}` })) : null, panelView === 'decade' ? (_jsx("span", { className: "kpt-calendar__title", children: `${centuryStart(page.y)} – ${centuryStart(page.y) + 119}` })) : null] }), hasNav ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", disabled: !canPageForward(page, panelView, maxDate), onClick: () => turnPage(1), "aria-label": navLabel('next'), children: _jsx(KptIcon, { name: "chevron-right" }) })) : null] }), panelView === 'day' ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "kpt-calendar__weekdays", children: weekdays.map((weekday) => (_jsx("span", { className: "kpt-calendar__weekday", children: weekday }, weekday))) }), _jsx("div", { className: "kpt-calendar__grid", onKeyDown: onDayKeyDown, children: weeks.flat().map((cell) => (_jsx("button", { type: "button", className: cn('kpt-calendar__day', !cell.inMonth && 'kpt-calendar__day--muted', cell.today && 'kpt-calendar__day--today', cell.selected && 'kpt-calendar__day--selected'), "data-iso": cell.iso, tabIndex: cell.iso === focusIso ? 0 : -1, "aria-label": dayName(cell.iso), "aria-current": cell.today ? 'date' : undefined, disabled: cell.disabled, "aria-pressed": cell.selected, onClick: () => selectDay(cell.iso, cell.disabled), children: cell.day }, cell.iso))) })] })) : (_jsx("div", { className: cn('kpt-calendar__grid kpt-calendar__grid--cells', panelView === 'decade' && 'kpt-calendar__grid--decades'), onKeyDown: onCellKeyDown, children: levelCells.map((cell, index) => (_jsx("button", { type: "button", className: cn('kpt-calendar__cell', cell.selected && 'kpt-calendar__cell--selected', cell.current && 'kpt-calendar__cell--current'), tabIndex: index === activeCell ? 0 : -1, disabled: cell.disabled, "aria-pressed": cell.selected, onClick: () => selectCell(cell), children: cell.label }, cell.label))) })), selectionMode === 'datetime' ? (_jsxs("button", { type: "button", className: "kpt-calendar__timebar", onClick: () => setDtView('clock'), children: [_jsx(KptIcon, { name: "clock" }), _jsx("span", { children: formatTime(timeParts?.h ?? 0, timeParts?.m ?? 0, hourFormat) })] })) : null] })), hasFooter ? (_jsx("div", { className: "kpt-calendar__footer", children: _jsx(KptButton, { size: "sm", onClick: commit, children: t('common.done') }) })) : null] }) })] }));
 }

package/dist/datepicker/llms.txt

@@ -26,9 +26,25 @@ Import: `import { KptDatepicker } from '@konce-pt/react';`
 - `hourFormat`: 12 | 24 (default 24) — the dial; the stored value is always 24h
 - `minuteStep`: number (default 1) — minute snapping on the dial
 - `open` / `onOpenChange` — the panel state, so it can be opened from outside
-- `placeholder`, `ariaLabel`, `disabled`, `invalid`, `touched`, `onTouch()`
+- `placeholder`, `ariaLabel`, `disabled`, `invalid`, `touched`
+- `onTouch()` — fires when the panel closes or focus leaves the closed trigger
 - `className`, `ref` and every other `<div>` prop go to the host
 
+## Keyboard
+The date picker dialog pattern. The trigger has `aria-haspopup="dialog"` and `aria-expanded`;
+`Enter`, `Space` and `↓` open the panel — a `role="dialog"` named "Choose a date" — and move focus to
+the selected day, or today, clamped to `minDate`/`maxDate`.
+- Day grid: `←`/`→` one day, `↑`/`↓` one week, `Home`/`End` Monday and Sunday of the week,
+  `PageUp`/`PageDown` one month, with `Shift` one year (the day is clamped to the month length).
+  Crossing a month edge turns the page. Each day is named with the full date from `Intl`
+  ("Thursday, October 8, 2026"), today has `aria-current="date"`, and only the focused day is
+  a Tab stop. In RTL the horizontal arrows are mirrored.
+- Month, year and decade grids: the arrows move between cells (three columns), `Home`/`End` to the ends.
+  Clicking a title moves focus to the new grid.
+- `Tab` cycles inside the panel; `Escape` closes it. Picking a value (or "Done") closes the panel
+  and returns focus to the trigger. `Delete`/`Backspace` on the trigger clears the value; the "×" button
+  sits outside the Tab order.
+
 ## The view stack
 The header is always `‹ title ›`: the arrows page the current level, the title goes one level up.
 
@@ -65,10 +81,18 @@ Weekday and month names come from `Intl` for the active locale, not from the dic
 navigation labels and "Done" come from the `datepicker` and `common` namespaces; `locale` and
 `dictionary` override them per instance.
 
+## 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`; the trigger is the element that carries it.
+
 ## Tokens
 `--kpt-form-field-{bg,text,border,border-focus,border-error,radius}`; the panel
 `--kpt-color-surface-raised`, the selection `--kpt-color-primary`.
 
 ## Accessibility
-The trigger is `role="button"` with `tabindex="0"` and Enter; every cell is a real `<button>` with
-`aria-pressed`; `ariaLabel` names the field when no `<label for>` describes it.
+The trigger is `role="button"` with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`;
+the panel is a named `role="dialog"`; every cell is a real `<button>` with `aria-pressed`, days carry
+the full date and `aria-current="date"`; `ariaLabel` names the field when no `<label for>` describes
+it. The keyboard is described above.

package/dist/dialog/dialog.d.ts

@@ -20,6 +20,10 @@ export interface KptDialogProps extends Omit<ComponentPropsWithRef<'dialog'>, 'o
  * Okno modalne na natywnym `<dialog>` — pułapka fokusu, Escape i backdrop pochodzą z platformy,
  * nie z naszego kodu. Stopkę wstaw przez `<KptDialog.Footer>`.
  *
+ * Z `header` okno bierze nazwę z nagłówka (`aria-labelledby`); bez niego podaj `aria-label`.
+ * Okno wymagające odpowiedzi dostaje `role="alertdialog"` i `aria-describedby` wprost z propsów
+ * `<dialog>` — tak robi `KptConfirmContainer`.
+ *
  * @example
  * <KptDialog open={open} onOpenChange={setOpen} header="Usunąć?">
  *   Tej operacji nie można cofnąć.

package/dist/dialog/dialog.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, isValidElement, useEffect, useRef, useState, } from 'react';
 import { cn } from "../internal/cn.js";
 import { composeRefs } from "../internal/compose-refs.js";
+import { useKptId } from "../internal/use-id.js";
 import { KptOverlayContainerContext } from "../internal/overlay-container.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
@@ -9,6 +10,10 @@ import { KptIcon } from "../icon/icon.js";
  * Okno modalne na natywnym `<dialog>` — pułapka fokusu, Escape i backdrop pochodzą z platformy,
  * nie z naszego kodu. Stopkę wstaw przez `<KptDialog.Footer>`.
  *
+ * Z `header` okno bierze nazwę z nagłówka (`aria-labelledby`); bez niego podaj `aria-label`.
+ * Okno wymagające odpowiedzi dostaje `role="alertdialog"` i `aria-describedby` wprost z propsów
+ * `<dialog>` — tak robi `KptConfirmContainer`.
+ *
  * @example
  * <KptDialog open={open} onOpenChange={setOpen} header="Usunąć?">
  *   Tej operacji nie można cofnąć.
@@ -21,6 +26,7 @@ import { KptIcon } from "../icon/icon.js";
 export function KptDialog({ open, onOpenChange, header = '', size = 'md', dismissible = true, locale, dictionary, className, children, ref, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const dialogRef = useRef(null);
+    const titleId = useKptId(undefined, 'kpt-dialog-title');
     // Element trafia do kontekstu, więc musi wywołać render — sam `ref` by nie wystarczył.
     const [dialogEl, setDialogEl] = useState(null);
     useEffect(() => {
@@ -46,7 +52,7 @@ export function KptDialog({ open, onOpenChange, header = '', size = 'md', dismis
         }
         onOpenChange(false);
     };
-    return (_jsx(KptOverlayContainerContext.Provider, { value: open ? dialogEl : null, children: _jsxs("dialog", { ref: composeRefs(dialogRef, setDialogEl, ref), className: cn('kpt-dialog', className), "data-size": size, onClose: () => onOpenChange(false), onCancel: onCancel, ...rest, children: [header ? (_jsxs("div", { className: "kpt-dialog__header", children: [_jsx("h2", { className: "kpt-dialog__title", children: header }), dismissible ? (_jsx("button", { className: "kpt-dialog__close", type: "button", onClick: () => onOpenChange(false), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })) : null] })) : null, _jsx("div", { className: "kpt-dialog__body", children: body }), footers] }) }));
+    return (_jsx(KptOverlayContainerContext.Provider, { value: open ? dialogEl : null, children: _jsxs("dialog", { ref: composeRefs(dialogRef, setDialogEl, ref), className: cn('kpt-dialog', className), "data-size": size, "aria-labelledby": header ? titleId : undefined, onClose: () => onOpenChange(false), onCancel: onCancel, ...rest, children: [header ? (_jsxs("div", { className: "kpt-dialog__header", children: [_jsx("h2", { className: "kpt-dialog__title", id: titleId, children: header }), dismissible ? (_jsx("button", { className: "kpt-dialog__close", type: "button", onClick: () => onOpenChange(false), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })) : null] })) : null, _jsx("div", { className: "kpt-dialog__body", children: body }), footers] }) }));
 }
 /**
  * Stopka okna. Nosi atrybut `kptdialogfooter`, w który celuje wspólny SCSS (nazwy atrybutów

package/dist/dialog/llms.txt

@@ -49,3 +49,5 @@ dialog; the mechanism differs, the result does not.
 A native `<dialog>` opened with `showModal()`: focus moves inside and is trapped, the rest of the
 page becomes inert, and Escape closes it — all from the browser. With `dismissible={false}` the
 `cancel` event is prevented, so Escape stops working; give the user another way out.
+With `header` the dialog is named by its title (`aria-labelledby`); without one pass `aria-label`.
+`role="alertdialog"` and `aria-describedby` go straight through as `<dialog>` props.

package/dist/drawer/drawer.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback } from 'react';
+import { useCallback, useRef } from 'react';
 import { cn } from "../internal/cn.js";
+import { useKptId } from "../internal/use-id.js";
+import { useModalFocus } from "../internal/use-modal-focus.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
 /**
@@ -17,9 +19,12 @@ import { KptIcon } from "../icon/icon.js";
 export function KptDrawer({ open, onOpenChange, position = 'left', header = '', dismissible = true, closeOnBackdrop = true, locale, dictionary, className, children, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const close = useCallback(() => onOpenChange(false), [onOpenChange]);
+    const panelRef = useRef(null);
+    const titleId = useKptId(undefined, 'kpt-drawer-title');
+    useModalFocus(open, panelRef);
     const onKeyDown = (event) => {
         if (event.key === 'Escape' && dismissible)
             close();
     };
-    return (_jsxs("div", { className: cn('kpt-drawer-host', className), ...rest, children: [_jsx("div", { className: cn('kpt-drawer__backdrop', open && 'is-open'), onClick: () => closeOnBackdrop && close() }), _jsxs("aside", { className: cn('kpt-drawer__panel', open && 'is-open'), "data-position": position, role: "dialog", "aria-modal": "true", tabIndex: -1, onKeyDown: onKeyDown, children: [header || dismissible ? (_jsxs("div", { className: "kpt-drawer__header", children: [_jsx("span", { className: "kpt-drawer__title", children: header }), dismissible ? (_jsx("button", { type: "button", className: "kpt-drawer__close", onClick: close, "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })) : null] })) : null, _jsx("div", { className: "kpt-drawer__body", children: children })] })] }));
+    return (_jsxs("div", { className: cn('kpt-drawer-host', className), ...rest, children: [_jsx("div", { className: cn('kpt-drawer__backdrop', open && 'is-open'), onClick: () => closeOnBackdrop && close() }), _jsxs("aside", { ref: panelRef, className: cn('kpt-drawer__panel', open && 'is-open'), "data-position": position, role: "dialog", "aria-modal": "true", "aria-labelledby": header ? titleId : undefined, tabIndex: -1, onKeyDown: onKeyDown, children: [header || dismissible ? (_jsxs("div", { className: "kpt-drawer__header", children: [_jsx("span", { className: "kpt-drawer__title", id: titleId, children: header }), dismissible ? (_jsx("button", { type: "button", className: "kpt-drawer__close", onClick: close, "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })) : null] })) : null, _jsx("div", { className: "kpt-drawer__body", children: children })] })] }));
 }

package/dist/drawer/llms.txt

@@ -29,9 +29,14 @@ That is what makes the slide animatable — mounting the panel on open would giv
 nothing to animate from.
 
 ## Not a native modal
-Unlike `KptDialog` this is a plain `<aside role="dialog" aria-modal="true">`, so the browser does
-not trap focus and does not make the rest of the page inert. Escape works while the focus is inside
-the panel. For a hard modal reach for `KptDialog`.
+Unlike `KptDialog` this is a plain `<aside role="dialog" aria-modal="true">`, not a native
+`<dialog>` — the focus handling below is done by the component, not by the browser.
+
+## Focus and keyboard
+Opening moves focus into the panel (its first focusable element, else the panel
+itself) and traps it there — `Tab` / `Shift+Tab` wrap inside, as `aria-modal="true"` promises.
+Closing returns focus to the element that had it before. `Escape` closes the panel — only when `dismissible`, like the `×` button. The panel
+is named by its `header` through `aria-labelledby`. The shared helper is `internal/use-modal-focus.ts` (the Angular port has a twin on the CDK focus trap).
 
 ## Examples
     <KptDrawer open={open} onOpenChange={setOpen} position="right" header="Filters">
@@ -43,5 +48,5 @@ the panel. For a hard modal reach for `KptDialog`.
 `--kpt-color-overlay-scrim`, `--kpt-motion-duration-base`, `--kpt-z-overlay`.
 
 ## Accessibility
-`role="dialog"` with `aria-modal="true"` and `tabindex="-1"`, so the panel can take focus. The close
-button gets its label from `common.close` in the dictionary.
+`role="dialog"`, `aria-modal="true"` and `aria-labelledby` pointing at the title; the close button gets
+its label from `common.close`. Focus handling — see "Focus and keyboard" above.

package/dist/empty/empty.d.ts

@@ -4,6 +4,11 @@ export interface KptEmptyProps extends Omit<ComponentPropsWithRef<'div'>, 'title
     icon?: string | null;
     title?: string;
     description?: string;
+    /**
+     * Robi z tytułu nagłówek strony (`role="heading"` z `aria-level`), żeby pusty stan pojawił się
+     * w strukturze dokumentu — np. gdy zastępuje całą sekcję. Bez tego tytuł to sam tekst.
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
     /** Akcje pod opisem. */
     children?: ReactNode;
 }
@@ -15,4 +20,4 @@ export interface KptEmptyProps extends Omit<ComponentPropsWithRef<'div'>, 'title
  *   <KptButton>Wyczyść filtry</KptButton>
  * </KptEmpty>
  */
-export declare function KptEmpty({ icon, title, description, className, children, ...rest }: Readonly<KptEmptyProps>): import("react").JSX.Element;
+export declare function KptEmpty({ icon, title, description, headingLevel, className, children, ...rest }: Readonly<KptEmptyProps>): import("react").JSX.Element;

package/dist/empty/empty.js

@@ -9,6 +9,6 @@ import { KptIcon } from "../icon/icon.js";
  *   <KptButton>Wyczyść filtry</KptButton>
  * </KptEmpty>
  */
-export function KptEmpty({ icon = 'info-circle', title = '', description = '', className, children, ...rest }) {
-    return (_jsx("div", { className: cn('kpt-empty-host', className), ...rest, children: _jsxs("div", { className: "kpt-empty", children: [icon ? (_jsx("div", { className: "kpt-empty__icon", children: _jsx(KptIcon, { name: icon }) })) : null, title ? _jsx("p", { className: "kpt-empty__title", children: title }) : null, description ? _jsx("p", { className: "kpt-empty__desc", children: description }) : null, _jsx("div", { className: "kpt-empty__actions", children: children })] }) }));
+export function KptEmpty({ icon = 'info-circle', title = '', description = '', headingLevel, className, children, ...rest }) {
+    return (_jsx("div", { className: cn('kpt-empty-host', className), ...rest, children: _jsxs("div", { className: "kpt-empty", children: [icon ? (_jsx("div", { className: "kpt-empty__icon", children: _jsx(KptIcon, { name: icon }) })) : null, title ? (_jsx("p", { className: "kpt-empty__title", role: headingLevel ? 'heading' : undefined, "aria-level": headingLevel, children: title })) : null, description ? _jsx("p", { className: "kpt-empty__desc", children: description }) : null, _jsx("div", { className: "kpt-empty__actions", children: children })] }) }));
 }

package/dist/empty/llms.txt

@@ -16,6 +16,7 @@ Import: `import { KptEmpty } from '@konce-pt/react';`
 ## Props
 - `icon`: string | null (default 'info-circle') — a registry icon name; `null` hides it
 - `title`: string, `description`: string — each row disappears when its text is empty
+- `headingLevel`: 1–6 | null (default null) — makes the title a heading (`role="heading"` + `aria-level`)
 - `children` — the actions under the description
 - `className`, `ref` and every other `<div>` prop go to the host
 
@@ -30,6 +31,6 @@ Import: `import { KptEmpty } from '@konce-pt/react';`
 `--kpt-color-on-surface-muted` (the description), `--kpt-space-*`.
 
 ## Accessibility
-A plain container with no role of its own — the title is a `<p>`, not a heading, so it does not
-break the heading outline of the page. Where the empty state IS the heading of its section, render
-your own `<h2>` in the children instead.
+The icon is decorative. The title is a styled paragraph unless `headingLevel` makes it a heading —
+use that when the empty state stands in for a whole section. Replacing results with an empty state
+is not announced; report “0 results” in a live region of your own.

package/dist/fab/llms.txt

@@ -31,7 +31,8 @@ pins it wherever the design wants (usually `position: fixed` in a corner).
 
 ## Tokens
 `--kpt-color-primary` / `--kpt-color-on-primary` (filled), `--kpt-color-muted` /
-`--kpt-color-on-muted` (tonal), `--kpt-elevation-3`, `--kpt-radius-full`.
+`--kpt-color-on-muted` (tonal), `--kpt-elevation-3` (`--kpt-elevation-4` on hover); shape
+`--kpt-radius-lg` (md), `--kpt-radius-md` (mini), `--kpt-radius-full` (extended).
 
 ## Accessibility
 A native `<button>`; in the round variant give it `aria-label`, in `extended` the text does the job.

package/dist/file-upload/file-upload.d.ts

@@ -16,6 +16,11 @@ export interface KptFileUploadProps extends Omit<ComponentPropsWithRef<'div'>, '
  * Wgrywanie plików: strefa reagująca na kliknięcie i na upuszczenie, plus lista wybranych plików.
  * Wartością jest tablica `File`.
  *
+ * Strefa to `role="button"` z jednym przystankiem Tab: `Enter` i spacja otwierają okno wyboru,
+ * tak jak kliknięcie — natywne pole pliku jest ukryte, więc bez tego klawiatura nie miałaby
+ * jak wybrać pliku. `disabled` wyjmuje strefę z kolejności Tab. Stan błędu: `invalid`
+ * i `touched` (pominięty `touched` = błąd widać od razu, jak w `KptInput`).
+ *
  * @example
  * <KptFileUpload value={files} onValueChange={setFiles} accept="image/*" multiple />
  */

package/dist/file-upload/file-upload.js

@@ -10,10 +10,19 @@ function formatSize(file) {
     const kb = file.size / 1024;
     return kb < 1024 ? `${kb.toFixed(0)} KB` : `${(kb / 1024).toFixed(1)} MB`;
 }
+/** Ikona pozycji listy: obrazek dla plików graficznych, spinacz dla pozostałych. */
+function fileIcon(file) {
+    return file.type.startsWith('image/') ? 'photo' : 'paperclip';
+}
 /**
  * Wgrywanie plików: strefa reagująca na kliknięcie i na upuszczenie, plus lista wybranych plików.
  * Wartością jest tablica `File`.
  *
+ * Strefa to `role="button"` z jednym przystankiem Tab: `Enter` i spacja otwierają okno wyboru,
+ * tak jak kliknięcie — natywne pole pliku jest ukryte, więc bez tego klawiatura nie miałaby
+ * jak wybrać pliku. `disabled` wyjmuje strefę z kolejności Tab. Stan błędu: `invalid`
+ * i `touched` (pominięty `touched` = błąd widać od razu, jak w `KptInput`).
+ *
  * @example
  * <KptFileUpload value={files} onValueChange={setFiles} accept="image/*" multiple />
  */
@@ -22,6 +31,18 @@ export function KptFileUpload({ value, defaultValue = EMPTY, onValueChange, acce
     const inputRef = useRef(null);
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const [dragover, setDragover] = useState(false);
+    const showError = invalid && (touched ?? true);
+    const openPicker = () => {
+        if (!disabled)
+            inputRef.current?.click();
+    };
+    /** `Enter` / spacja na strefie — spacja bez `preventDefault` przewinęłaby stronę. */
+    const onZoneKeyDown = (event) => {
+        if (event.key !== 'Enter' && event.key !== ' ')
+            return;
+        event.preventDefault();
+        openPicker();
+    };
     const addFiles = (list) => {
         if (!list?.length)
             return;
@@ -34,7 +55,7 @@ export function KptFileUpload({ value, defaultValue = EMPTY, onValueChange, acce
         // Czyszczenie pola pozwala wybrać ten sam plik drugi raz — inaczej `change` by nie poleciał.
         event.target.value = '';
     };
-    return (_jsxs("div", { className: cn('kpt-file-upload-host', className), ...rest, children: [_jsxs("div", { className: cn('kpt-file-upload__zone', dragover && 'is-dragover', disabled && 'is-disabled'), onClick: () => !disabled && inputRef.current?.click(), onDragOver: (event) => {
+    return (_jsxs("div", { className: cn('kpt-file-upload-host', className), ...rest, children: [_jsxs("div", { className: cn('kpt-file-upload__zone', dragover && 'is-dragover', disabled && 'is-disabled'), role: "button", tabIndex: disabled ? -1 : 0, "aria-disabled": disabled || undefined, "aria-invalid": showError || undefined, "data-invalid": showError ? '' : undefined, onClick: openPicker, onKeyDown: onZoneKeyDown, onDragOver: (event) => {
                     event.preventDefault();
                     if (!disabled)
                         setDragover(true);
@@ -43,8 +64,8 @@ export function KptFileUpload({ value, defaultValue = EMPTY, onValueChange, acce
                     setDragover(false);
                     if (!disabled)
                         addFiles(event.dataTransfer?.files);
-                }, children: [_jsx("input", { ref: inputRef, type: "file", hidden: true, accept: accept, multiple: multiple, onChange: onSelect }), _jsx(KptIcon, { name: "upload", className: "kpt-file-upload__icon" }), _jsx("div", { className: "kpt-file-upload__text", dangerouslySetInnerHTML: { __html: t('fileUpload.hint') } }), accept ? _jsx("div", { className: "kpt-file-upload__hint", children: accept }) : null] }), current.length ? (_jsx("ul", { className: "kpt-file-upload__list", children: current.map((file) => (_jsxs("li", { className: "kpt-file-upload__file", children: [_jsx(KptIcon, { name: "photo" }), _jsx("span", { className: "kpt-file-upload__name", children: file.name }), _jsx("span", { className: "kpt-file-upload__size", children: formatSize(file) }), _jsx("button", { type: "button", className: "kpt-file-upload__remove", "aria-label": t('fileUpload.remove'), onClick: (event) => {
+                }, children: [_jsx("input", { ref: inputRef, type: "file", hidden: true, accept: accept, multiple: multiple, onChange: onSelect }), _jsx(KptIcon, { name: "upload", className: "kpt-file-upload__icon" }), _jsx("div", { className: "kpt-file-upload__text", dangerouslySetInnerHTML: { __html: t('fileUpload.hint') } }), accept ? _jsx("div", { className: "kpt-file-upload__hint", children: accept }) : null] }), current.length ? (_jsx("ul", { className: "kpt-file-upload__list", children: current.map((file, index) => (_jsxs("li", { className: "kpt-file-upload__file", children: [_jsx(KptIcon, { name: fileIcon(file) }), _jsx("span", { className: "kpt-file-upload__name", children: file.name }), _jsx("span", { className: "kpt-file-upload__size", children: formatSize(file) }), _jsx("button", { type: "button", className: "kpt-file-upload__remove", "aria-label": t('fileUpload.remove'), onClick: (event) => {
                                 event.stopPropagation();
                                 setCurrent(current.filter((item) => item !== file));
-                            }, children: _jsx(KptIcon, { name: "trash" }) })] }, file.name))) })) : null] }));
+                            }, children: _jsx(KptIcon, { name: "trash" }) })] }, `${index}-${file.name}`))) })) : null] }));
 }

package/dist/file-upload/llms.txt

@@ -6,7 +6,7 @@ Import: `import { KptFileUpload } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-file-upload-host">
-      <div class="kpt-file-upload__zone is-dragover">
+      <div class="kpt-file-upload__zone is-dragover" role="button" tabindex="0">
         <input type="file" hidden>
         <span class="kpt-icon-host kpt-file-upload__icon">…</span>
         <div class="kpt-file-upload__text"><strong>Click</strong> or drag files here</div>
@@ -40,9 +40,20 @@ comes from the dictionary (ours or the app's), never from user input.
 The zone hint and the remove label come from the `fileUpload` namespace; `locale` and `dictionary`
 override them per instance.
 
+## Keyboard and states
+- The zone is `role="button"` with a single Tab stop: `Enter` and `Space` open the file picker,
+  the same as a click. The native `<input type="file">` is hidden, so without this a keyboard user
+  could not pick a file at all.
+- `disabled` takes the zone out of the Tab order (`tabindex="-1"`, `aria-disabled`) and blocks
+  both picking and dropping.
+- The error state (`aria-invalid`, a `--kpt-color-danger` border via `[data-invalid]`) shows once
+  the field is invalid and touched (an omitted `touched` shows it right away, as in `KptInput`).
+- List items get an icon by type: `photo` for `image/*`, `paperclip` for anything else.
+
 ## Tokens
-The zone `--kpt-form-field-border` (dashed), the dragover state `--kpt-color-primary`.
+The zone `--kpt-color-border-strong` (dashed), hover / dragover `--kpt-color-primary`, error `--kpt-color-danger`,
+focus ring `--kpt-color-focus-ring`.
 
 ## Accessibility
-The remove button is labelled from the dictionary; the file input stays a real `<input type="file">`,
-so the system picker and its keyboard path are untouched.
+The remove button is labelled from the dictionary. The zone itself is the keyboard path to the
+system picker — see "Keyboard and states" above.