@konce-pt/react 0.9.0 → 0.10.0

package/dist/color-picker/color-picker.js

@@ -1,17 +1,22 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
-import { useKptFormFieldContext } from "../form-field/form-field-context.js";
-const DEFAULT_PRESETS = [
-    '#ef4444',
-    '#f59e0b',
-    '#10b981',
-    '#3b82f6',
-    '#8b5cf6',
-    '#ec4899',
-    '#111827',
-    '#ffffff',
-];
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
+const DEFAULT_PRESETS = ['#ef4444', '#f59e0b', '#10b981', '#3b82f6', '#8b5cf6', '#ec4899', '#111827', '#ffffff'];
+/** Nazwy domyślnej palety (klucze `colorPicker.*`). */
+const DEFAULT_NAMES = {
+    '#ef4444': 'red',
+    '#f59e0b': 'amber',
+    '#10b981': 'green',
+    '#3b82f6': 'blue',
+    '#8b5cf6': 'violet',
+    '#ec4899': 'pink',
+    '#111827': 'black',
+    '#ffffff': 'white',
+};
+const HEX = /^#[0-9a-f]{6}$/i;
 /**
  * Wybór koloru: próbka, pole hex i presety. Wartością jest hex.
  *
@@ -21,8 +26,37 @@ const DEFAULT_PRESETS = [
  * @example
  * <KptColorPicker value={color} onValueChange={setColor} />
  */
-export function KptColorPicker({ value, defaultValue = '#3b82f6', onValueChange, presets = DEFAULT_PRESETS, disabled = false, invalid = false, touched, onTouch, className, ...rest }) {
-    const field = useKptFormFieldContext();
+export function KptColorPicker({ value, defaultValue = '#3b82f6', onValueChange, presets = DEFAULT_PRESETS, id, ariaLabel = null, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
+    const field = useKptFieldA11y(id, 'kpt-color-picker');
+    /** Tekst w polu hex, dopóki nie jest poprawnym kodem — wartość zmienia się dopiero na `#rrggbb`. */
+    const [hexDraft, setHexDraft] = useState(null);
+    const hexInvalid = hexDraft !== null && !HEX.test(hexDraft);
+    const presetList = presets.map((preset) => {
+        const item = typeof preset === 'string' ? { value: preset, label: '' } : preset;
+        const named = DEFAULT_NAMES[item.value.toLowerCase()];
+        return { value: item.value, label: item.label || (named ? t(`colorPicker.${named}`) : item.value) };
+    });
+    const isActive = (color) => color.toLowerCase() === current.toLowerCase();
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
-    return (_jsx("div", { className: cn('kpt-color-picker-host', className), ...rest, children: _jsxs("div", { className: "kpt-color-picker", children: [_jsx("label", { className: "kpt-color-picker__swatch", style: { backgroundColor: current }, children: _jsx("input", { type: "color", value: current, disabled: disabled, onChange: (event) => setCurrent(event.target.value), onBlur: () => onTouch?.() }) }), _jsx("input", { type: "text", className: "kpt-color-picker__hex", id: field?.controlId, value: current, disabled: disabled, maxLength: 7, "aria-invalid": (invalid && (touched ?? true)) || undefined, onChange: (event) => setCurrent(event.target.value), onBlur: () => onTouch?.() }), _jsx("div", { className: "kpt-color-picker__presets", children: presets.map((color) => (_jsx("button", { type: "button", className: cn('kpt-color-picker__preset', color === current && 'is-active'), style: { backgroundColor: color }, disabled: disabled, onClick: () => setCurrent(color), "aria-label": color }, color))) })] }) }));
+    return (_jsx("div", { className: cn('kpt-color-picker-host', className), ...rest, children: _jsxs("div", { className: "kpt-color-picker", children: [_jsx("label", { className: "kpt-color-picker__swatch", style: { backgroundColor: current }, children: _jsx("input", { type: "color", value: current, disabled: disabled, "aria-label": t('colorPicker.picker'), onChange: (event) => setCurrent(event.target.value), onBlur: () => onTouch?.() }) }), _jsx("input", { type: "text", className: "kpt-color-picker__hex", id: field.id, "aria-label": field.labelledBy ? undefined : (ariaLabel ?? t('colorPicker.hex')), "aria-describedby": field.describedBy, value: hexDraft ?? current, disabled: disabled, maxLength: 7, "aria-invalid": (invalid && (touched ?? true)) || hexInvalid || undefined, onChange: (event) => {
+                        let text = event.target.value.trim();
+                        if (text && !text.startsWith('#'))
+                            text = `#${text}`;
+                        if (HEX.test(text)) {
+                            setHexDraft(null);
+                            setCurrent(text.toLowerCase());
+                        }
+                        else {
+                            setHexDraft(text);
+                        }
+                    }, onBlur: () => {
+                        // Wyjście z pola z niepełnym kodem zostawia go widocznym i oznaczonym `aria-invalid`.
+                        if (hexDraft === '')
+                            setHexDraft(null);
+                        onTouch?.();
+                    } }), _jsx("div", { className: "kpt-color-picker__presets", children: presetList.map((preset) => (_jsx("button", { type: "button", className: cn('kpt-color-picker__preset', isActive(preset.value) && 'is-active'), style: { backgroundColor: preset.value }, disabled: disabled, "aria-pressed": isActive(preset.value), onClick: () => {
+                            setHexDraft(null);
+                            setCurrent(preset.value);
+                        }, "aria-label": preset.label }, preset.value))) })] }) }));
 }

package/dist/color-picker/llms.txt

@@ -31,6 +31,20 @@ same value as text, and the presets write it directly.
     <KptColorPicker value={color} onValueChange={setColor} />
     <KptColorPicker value={color} onValueChange={setColor} presets={['#ef4444', '#3b82f6']} />
 
+## Screen reader and keyboard
+`presets` accepts codes or `{ value, label }` (the `KptColorPreset` type): the label names the
+swatch, because a hex code says little to a screen reader; the default palette is named from i18n
+(`colorPicker.red`…). The active swatch has `aria-pressed`. The hex field changes the value only on
+a full `#rrggbb` code (a missing `#` is added); an incomplete code stays visible with
+`aria-invalid`.
+
+## 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`.
+`id` and the label go to the hex field; the native colour well is named "Pick a colour"
+(`colorPicker.picker`), and the hex field falls back to "Hex code" (`colorPicker.hex`).
+
 ## Tokens
 The border `--kpt-form-field-border`, the field `--kpt-form-field-{bg,text,radius}`, the active
 preset `--kpt-color-focus-ring`.

package/dist/confirm/confirm-container.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithRef } from 'react';
+import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptConfirmContainerProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
 }
@@ -6,6 +6,10 @@ export interface KptConfirmContainerProps extends ComponentPropsWithRef<'div'>,
  * Kontener potwierdzeń — renderuje żądanie z `kptConfirm()` na `KptDialog`. Umieść raz
  * w aplikacji, obok `<KptToastContainer />`.
  *
+ * Okno to `role="alertdialog"` z treścią pytania w `aria-describedby`, więc czytnik odczytuje
+ * je od razu po otwarciu. Fokus startuje na przycisku odmowy — bezpieczniejszej odpowiedzi,
+ * której przypadkowy `Enter` niczego nie usunie.
+ *
  * @example
  * <KptConfirmContainer />
  * // gdziekolwiek: if (await kptConfirm({ message: 'Usunąć?' })) { … }

package/dist/confirm/confirm-container.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
 import { cn } from "../internal/cn.js";
+import { useKptId } from "../internal/use-id.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptButton } from "../button/button.js";
 import { KptDialog } from "../dialog/dialog.js";
@@ -9,6 +11,10 @@ import { acceptKptConfirm, rejectKptConfirm, useKptConfirmRequest } from "./conf
  * Kontener potwierdzeń — renderuje żądanie z `kptConfirm()` na `KptDialog`. Umieść raz
  * w aplikacji, obok `<KptToastContainer />`.
  *
+ * Okno to `role="alertdialog"` z treścią pytania w `aria-describedby`, więc czytnik odczytuje
+ * je od razu po otwarciu. Fokus startuje na przycisku odmowy — bezpieczniejszej odpowiedzi,
+ * której przypadkowy `Enter` niczego nie usunie.
+ *
  * @example
  * <KptConfirmContainer />
  * // gdziekolwiek: if (await kptConfirm({ message: 'Usunąć?' })) { … }
@@ -16,11 +22,19 @@ import { acceptKptConfirm, rejectKptConfirm, useKptConfirmRequest } from "./conf
 export function KptConfirmContainer({ locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const request = useKptConfirmRequest();
+    const messageId = useKptId(undefined, 'kpt-confirm-message');
+    const rejectRef = useRef(null);
+    // `showModal()` skupia pierwszy element okna, czyli „×” w nagłówku. Efekt dziecka (`KptDialog`)
+    // biegnie przed efektem rodzica, więc tu okno jest już otwarte i fokus można przenieść.
+    useEffect(() => {
+        if (request)
+            rejectRef.current?.focus();
+    }, [request]);
     return (_jsx("div", { className: cn('kpt-confirm-container-host', className), ...rest, children: _jsxs(KptDialog, { open: request !== null, 
             // Escape i × zamykają okno bez odpowiedzi — traktujemy to jak odmowę, żeby czekający
             // `await` zawsze coś dostał.
             onOpenChange: (open) => {
                 if (!open)
                     rejectKptConfirm();
-            }, header: request?.header ?? t('confirm.header'), locale: locale, dictionary: dictionary, children: [_jsxs("div", { className: "kpt-confirm__body", children: [request?.icon ? (_jsx(KptIcon, { className: "kpt-confirm__icon", name: request.icon, "data-variant": request.variant ?? 'filled' })) : null, _jsx("p", { className: "kpt-confirm__message", children: request?.message })] }), _jsxs(KptDialog.Footer, { children: [_jsx(KptButton, { variant: "text", onClick: rejectKptConfirm, children: request?.rejectLabel ?? t('confirm.reject') }), _jsx(KptButton, { variant: request?.variant ?? 'filled', onClick: acceptKptConfirm, children: request?.acceptLabel ?? t('confirm.accept') })] })] }) }));
+            }, header: request?.header ?? t('confirm.header'), role: "alertdialog", "aria-describedby": messageId, locale: locale, dictionary: dictionary, children: [_jsxs("div", { className: "kpt-confirm__body", children: [request?.icon ? (_jsx(KptIcon, { className: "kpt-confirm__icon", name: request.icon, "data-variant": request.variant ?? 'filled' })) : null, _jsx("p", { className: "kpt-confirm__message", id: messageId, children: request?.message })] }), _jsxs(KptDialog.Footer, { children: [_jsx(KptButton, { ref: rejectRef, variant: "text", onClick: rejectKptConfirm, children: request?.rejectLabel ?? t('confirm.reject') }), _jsx(KptButton, { variant: request?.variant ?? 'filled', onClick: acceptKptConfirm, children: request?.acceptLabel ?? t('confirm.accept') })] })] }) }));
 }

package/dist/confirm/llms.txt

@@ -40,5 +40,7 @@ Inherited from `KptDialog`; the icon follows the variant (`--kpt-color-danger` /
 `--kpt-color-primary`).
 
 ## Accessibility
-Everything comes from `KptDialog`, that is from the native `<dialog>`: the focus trap, Escape and
-the backdrop are the platform's, not ours.
+Built on `KptDialog`, so the focus trap, Escape and the backdrop are the native `<dialog>`'s.
+The window is `role="alertdialog"` named by its header, with the message tied to it through
+`aria-describedby`, so a screen reader reads the question as soon as it opens. Focus starts on the
+reject button — the safe answer, so a stray `Enter` deletes nothing. Escape and × reject.

package/dist/context-menu/context-menu.d.ts

@@ -9,6 +9,11 @@ export interface KptContextMenuProps<T> extends Omit<ComponentPropsWithRef<'div'
 /**
  * Menu kontekstowe (PPM) na obszarze dzieci. Panel pozycjonowany do kursora.
  *
+ * Klawiatura jak w `KptMenu` (wspólne `menu-keys.ts`): po otwarciu fokus na pierwszej pozycji,
+ * strzałki / `Home` / `End` chodzą po pozycjach, `Escape` i `Tab` zamykają, a fokus wraca tam,
+ * gdzie był. `Shift+F10` i klawisz Menu na skupionym elemencie obszaru też otwierają menu
+ * (panel staje wtedy przy tym elemencie). Panel jest dociskany do krawędzi okna.
+ *
  * W odróżnieniu od `KptMenu` panel nie idzie przez `KptOverlay` — nie ma tu wyzwalacza,
  * względem którego dałoby się go przypiąć; pozycję wyznaczają współrzędne kliknięcia,
  * a wygląd i warstwę niesie wspólny SCSS (`.kpt-context-menu__panel`).

package/dist/context-menu/context-menu.js

@@ -1,10 +1,18 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { MenuRows } from "../menu/menu-rows.js";
+import { focusMenuEdge, handleMenuKeydown } from "../menu/menu-keys.js";
+/** Odstęp panelu od krawędzi okna przy dociskaniu. */
+const EDGE = 8;
 /**
  * Menu kontekstowe (PPM) na obszarze dzieci. Panel pozycjonowany do kursora.
  *
+ * Klawiatura jak w `KptMenu` (wspólne `menu-keys.ts`): po otwarciu fokus na pierwszej pozycji,
+ * strzałki / `Home` / `End` chodzą po pozycjach, `Escape` i `Tab` zamykają, a fokus wraca tam,
+ * gdzie był. `Shift+F10` i klawisz Menu na skupionym elemencie obszaru też otwierają menu
+ * (panel staje wtedy przy tym elemencie). Panel jest dociskany do krawędzi okna.
+ *
  * W odróżnieniu od `KptMenu` panel nie idzie przez `KptOverlay` — nie ma tu wyzwalacza,
  * względem którego dałoby się go przypiąć; pozycję wyznaczają współrzędne kliknięcia,
  * a wygląd i warstwę niesie wspólny SCSS (`.kpt-context-menu__panel`).
@@ -17,12 +25,48 @@ import { MenuRows } from "../menu/menu-rows.js";
 export function KptContextMenu({ items = [], children, onSelect, className, ...rest }) {
     const [open, setOpen] = useState(false);
     const [point, setPoint] = useState({ x: 0, y: 0 });
+    const panelRef = useRef(null);
+    /** Element, który miał fokus przed otwarciem — tam fokus wraca po zamknięciu. */
+    const returnTo = useRef(null);
     const onContextMenu = (event) => {
         event.preventDefault();
-        setPoint({ x: event.clientX, y: event.clientY });
+        const active = document.activeElement;
+        returnTo.current = active instanceof HTMLElement ? active : null;
+        // Z klawiatury (`Shift+F10`, klawisz Menu) zdarzenie nie niesie pozycji myszy.
+        if (event.clientX === 0 && event.clientY === 0 && event.target instanceof HTMLElement) {
+            const r = event.target.getBoundingClientRect();
+            setPoint({ x: r.left, y: r.bottom });
+        }
+        else {
+            setPoint({ x: event.clientX, y: event.clientY });
+        }
         setOpen(true);
     };
-    const close = () => setOpen(false);
+    // Po otwarciu: dociśnięcie do okna i fokus na pierwszej pozycji.
+    useEffect(() => {
+        const panel = panelRef.current;
+        if (!open || !panel)
+            return;
+        const r = panel.getBoundingClientRect();
+        const maxX = window.innerWidth - r.width - EDGE;
+        const maxY = window.innerHeight - r.height - EDGE;
+        if (point.x > maxX || point.y > maxY) {
+            setPoint({ x: Math.max(EDGE, Math.min(point.x, maxX)), y: Math.max(EDGE, Math.min(point.y, maxY)) });
+        }
+        focusMenuEdge(panel, 'first');
+        // Celowo tylko `open`: dociśnięcie zmienia `point`, a ponowne uruchomienie przeniosłoby fokus.
+    }, [open]);
+    const close = () => {
+        setOpen(false);
+        const target = returnTo.current;
+        returnTo.current = null;
+        if (target?.isConnected)
+            target.focus();
+    };
+    const onPanelKeyDown = (event) => {
+        if (panelRef.current && handleMenuKeydown(panelRef.current, event.nativeEvent) === 'close')
+            close();
+    };
     const pick = (item) => {
         if (item.disabled)
             return;
@@ -32,5 +76,5 @@ export function KptContextMenu({ items = [], children, onSelect, className, ...r
     return (_jsxs("div", { className: cn('kpt-context-menu-host', className), ...rest, children: [_jsx("div", { className: "kpt-context-menu__area", onContextMenu: onContextMenu, children: children }), open ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "kpt-context-menu__backdrop", onClick: close, onContextMenu: (event) => {
                             event.preventDefault();
                             close();
-                        } }), _jsx("div", { className: "kpt-context-menu__panel", role: "menu", style: { left: point.x, top: point.y }, children: _jsx(MenuRows, { items: items, block: "kpt-context-menu", onPick: pick }) })] })) : null] }));
+                        } }), _jsx("div", { ref: panelRef, className: "kpt-context-menu__panel", role: "menu", style: { left: point.x, top: point.y }, onKeyDown: onPanelKeyDown, children: _jsx(MenuRows, { items: items, block: "kpt-context-menu", onPick: pick }) })] })) : null] }));
 }

package/dist/context-menu/llms.txt

@@ -23,7 +23,15 @@ the position comes from the click coordinates, and the look and the layer come f
 
 ## Closing
 A left click on the backdrop closes it; a right click on the backdrop closes it too and does not
-open the browser's own menu. Picking an item closes it and reports the choice.
+open the browser's own menu. Picking an item closes it and reports the choice; `Escape` closes it too.
+
+## Keyboard
+The same model as `KptMenu` (the shared `menu-keys.ts`): opening moves focus to the first item, arrows /
+`Home` / `End` move between items (disabled ones and separators are skipped), `Escape` and `Tab` close
+it and focus returns to where it was. `Shift+F10` and the context-menu key on a focused element inside
+the area open it too — the browser then sends `contextmenu` without mouse coordinates, so the panel is
+placed at that element. The panel is kept inside the viewport (8px from the edges). Touch screens have
+no right click, so still offer the same actions through a visible button with `KptMenu`.
 
 ## Examples
     <KptContextMenu items={items} onSelect={onSelect}>
@@ -34,6 +42,5 @@ open the browser's own menu. Picking an item closes it and reports the choice.
 `--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-elevation-3`, `--kpt-color-danger`.
 
 ## Accessibility
-The panel is `role="menu"` with `role="menuitem"` buttons. There is no keyboard path to open it —
-that is what the right mouse button and the platform's context key are for, so pair the same actions
-with a `KptMenu` when they must be reachable from the keyboard.
+The panel is `role="menu"` with `role="menuitem"` buttons at `tabindex="-1"` (one Tab stop). Keyboard — see
+"Keyboard" above.

package/dist/date-range/date-range.d.ts

@@ -13,6 +13,14 @@ export interface KptDateRangeProps extends Omit<ComponentPropsWithRef<'div'>, 'o
     minuteStep?: number;
     placeholder?: string;
     displayFormat?: 'pl' | 'iso';
+    /** Najwcześniejsza dozwolona data 'RRRR-MM-DD' (włącznie). */
+    minDate?: string | null;
+    /** Najpóźniejsza dozwolona data 'RRRR-MM-DD' (włącznie). */
+    maxDate?: string | null;
+    /** Nazwa dostępna pola, gdy nie opisuje go `<label for>`. */
+    ariaLabel?: string | null;
+    /** Id pola (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -23,8 +31,13 @@ export interface KptDateRangeProps extends Omit<ComponentPropsWithRef<'div'>, 'o
  * `visibleMonths` pokazuje kilka miesięcy obok siebie, a zakres podświetla się ciągłym pasmem
  * przez wszystkie panele.
  *
+ * Klawiatura jak w `KptDatepicker`: `Enter`/`Spacja`/`↓` otwierają panel z fokusem na początku
+ * zakresu (albo dziś), strzałki, `Home`/`End` i `PageUp`/`PageDown` (z `Shift` — rok) chodzą po
+ * dniach przez wszystkie panele, `Tab` krąży w panelu, `Escape` i wybór końca oddają fokus polu.
+ * Krańce i środek zakresu są w nazwie dnia („…, początek zakresu”), a wybór ogłasza region `polite`.
+ *
  * @example
  * <KptDateRange value={period} onValueChange={setPeriod} visibleMonths={2} />
  * <KptDateRange mode="datetime" hourFormat={12} value={span} onValueChange={setSpan} />
  */
-export declare function KptDateRange({ value, defaultValue, onValueChange, mode, visibleMonths, hourFormat, minuteStep, placeholder, displayFormat, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptDateRangeProps>): import("react").JSX.Element;
+export declare function KptDateRange({ value, defaultValue, onValueChange, mode, visibleMonths, hourFormat, minuteStep, placeholder, displayFormat, minDate, maxDate, ariaLabel, id, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptDateRangeProps>): import("react").JSX.Element;

package/dist/date-range/date-range.js

@@ -1,31 +1,48 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useRef, useState } from 'react';
-import { buildRangeGrid, clampVisibleMonths, datePart, formatDate, formatTime, pad, parseTime, pickRangeDay, timePart, toIso, } from '@konce-pt/datetime';
+import { useEffect, useRef, useState } from 'react';
+import { buildRangeGrid, clampVisibleMonths, datePart, formatDate, formatTime, initialFocusDate, moveFocusDate, pad, parseDate, parseTime, pickRangeDay, timePart, 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";
 const EMPTY_RANGE = { start: '', end: '' };
 /**
  * Wybór zakresu dat (i godzin) z kalendarzem. Pierwszy klik ustawia początek, drugi koniec;
  * `visibleMonths` pokazuje kilka miesięcy obok siebie, a zakres podświetla się ciągłym pasmem
  * przez wszystkie panele.
  *
+ * Klawiatura jak w `KptDatepicker`: `Enter`/`Spacja`/`↓` otwierają panel z fokusem na początku
+ * zakresu (albo dziś), strzałki, `Home`/`End` i `PageUp`/`PageDown` (z `Shift` — rok) chodzą po
+ * dniach przez wszystkie panele, `Tab` krąży w panelu, `Escape` i wybór końca oddają fokus polu.
+ * Krańce i środek zakresu są w nazwie dnia („…, początek zakresu”), a wybór ogłasza region `polite`.
+ *
  * @example
  * <KptDateRange value={period} onValueChange={setPeriod} visibleMonths={2} />
  * <KptDateRange mode="datetime" hourFormat={12} value={span} onValueChange={setSpan} />
  */
-export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange, mode = 'date', visibleMonths = 1, hourFormat = 24, minuteStep = 1, placeholder, displayFormat = 'pl', disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange, mode = 'date', visibleMonths = 1, hourFormat = 24, minuteStep = 1, placeholder, displayFormat = 'pl', minDate = null, maxDate = null, 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-date-range');
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const [isOpen, setOpen] = useState(false);
     const [anchor, setAnchor] = useState(null);
+    const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    const panelId = useKptId(undefined, 'kpt-date-range-panel');
+    /** Dzień z fokusem — jedyny przystanek Tab siatek dni (roving tabindex przez wszystkie panele). */
+    const [focusIso, setFocusIso] = useState('');
+    /** Komunikat regionu `polite` po wyborze początku i całego zakresu. */
+    const [announcement, setAnnouncement] = useState('');
+    /** Prośba o przeniesienie fokusu po najbliższym renderze (otwarcie, ruch klawiszem). */
+    const wantFocus = useRef(false);
     const today = useRef(new Date()).current;
     const todayIso = toIso(today);
     const showInvalid = invalid && (touched ?? true);
@@ -40,6 +57,22 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
     const weekdays = weekdayNames(activeLocale);
     const panelCount = mode === 'time' ? 1 : clampVisibleMonths(visibleMonths);
     const multi = panelCount > 1;
+    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;
+    };
+    /** Pełna nazwa dnia z rolą w zakresie — kolor pasma nie jest jedynym nośnikiem informacji. */
+    const dayLabel = (cell) => {
+        const name = dayName(cell.iso);
+        if (cell.isStart)
+            return t('dateRange.rangeStart', { date: name });
+        if (cell.isEnd)
+            return t('dateRange.rangeEnd', { date: name });
+        if (cell.inRange)
+            return t('dateRange.inRange', { date: name });
+        return name;
+    };
     const fmtTime = (hhmm) => {
         const parsed = parseTime(hhmm);
         return parsed ? formatTime(parsed.h, parsed.m, hourFormat) : '';
@@ -68,9 +101,11 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
             return;
         if (!isOpen) {
             const { start, end } = current;
-            const base = datePart(start) || todayIso;
-            const [y, m] = [+base.slice(0, 4), +base.slice(5, 7) - 1];
-            setPage({ y, m });
+            const focus = initialFocusDate(datePart(start), todayIso, minDate, maxDate);
+            setFocusIso(focus);
+            setAnnouncement('');
+            setPage({ y: +focus.slice(0, 4), m: +focus.slice(5, 7) - 1 });
+            wantFocus.current = true;
             if (mode === 'datetime') {
                 setStartDate(datePart(start));
                 setEndDate(datePart(end));
@@ -91,6 +126,59 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
         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);
+    });
+    /** Przesuwa okno paneli tak, żeby miesiąc dnia `iso` był widoczny — z najmniejszym skokiem. */
+    const revealMonth = (iso) => {
+        const target = +iso.slice(0, 4) * 12 + (+iso.slice(5, 7) - 1);
+        const first = page.y * 12 + page.m;
+        if (target < first)
+            setPage({ y: Math.floor(target / 12), m: target % 12 });
+        else if (target > first + panelCount - 1) {
+            const start = target - panelCount + 1;
+            setPage({ y: Math.floor(start / 12), m: start % 12 });
+        }
+    };
+    const onDayKeyDown = (event) => {
+        const rtl = !!panelRef.current && getComputedStyle(panelRef.current).direction === 'rtl';
+        const next = moveFocusDate(focusIso, event.key, { shift: event.shiftKey, rtl, minDate, maxDate });
+        if (next === null)
+            return;
+        event.preventDefault();
+        setFocusIso(next);
+        revealMonth(next);
+        wantFocus.current = true;
+    };
+    /** Strzałki ‹ ›: fokus zostaje na strzałce, ale przystanek siatki idzie za stroną. */
+    const turnPage = (dir) => {
+        const first = page.y * 12 + page.m + dir;
+        setPage({ y: Math.floor(first / 12), m: ((first % 12) + 12) % 12 });
+        const moved = moveFocusDate(focusIso, dir === 1 ? 'PageDown' : 'PageUp', { minDate, maxDate });
+        if (moved) {
+            const target = +moved.slice(0, 4) * 12 + (+moved.slice(5, 7) - 1);
+            // Nowe okno zaczyna się od `first` — dzień spoza niego nie dostałby przystanku Tab.
+            if (target >= first && target < first + panelCount)
+                setFocusIso(moved);
+        }
+    };
+    const announce = (start, end) => {
+        setAnnouncement(end
+            ? t('dateRange.picked', { start: dayName(start), end: dayName(end) })
+            : t('dateRange.pickEnd', { date: dayName(start) }));
+    };
     const panels = Array.from({ length: panelCount }, (_, i) => {
         const first = new Date(page.y, page.m + i, 1);
         const py = first.getFullYear();
@@ -104,21 +192,26 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
                 end: mode === 'datetime' ? endDate : current.end,
                 todayIso,
                 hideOutside: multi,
+                minDate,
+                maxDate,
             }),
         };
     });
     const selectDay = (iso) => {
+        setFocusIso(iso);
         if (mode === 'datetime') {
             const next = pickRangeDay({ start: startDate, end: endDate }, iso);
             setStartDate(next.start);
             setEndDate(next.end);
+            announce(next.start, next.end);
             return; // czas do wyboru → zamknięcie przez „Gotowe"
         }
         const next = pickRangeDay(current, iso);
         setCurrent(next);
+        announce(next.start, next.end);
         // Panel zostaje otwarty do czasu domknięcia zakresu — inaczej drugi klik nie miałby gdzie paść.
         if (next.end)
-            close();
+            closeAndFocus();
     };
     const commit = () => {
         if (mode === 'time') {
@@ -135,7 +228,7 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
             const end = `${endDate || startDate}T${endTime || '00:00'}`;
             setCurrent(start <= end ? { start, end } : { start: end, end: start });
         }
-        close();
+        closeAndFocus();
     };
     const clear = (event) => {
         event.stopPropagation();
@@ -145,11 +238,34 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
     };
     const clockValue = timeEnd === 'start' ? startTime : endTime;
     const setClockValue = timeEnd === 'start' ? setStartTime : setEndTime;
-    return (_jsxs("div", { className: cn('kpt-date-range-host', className), ...rest, children: [_jsxs("div", { ref: setAnchor, className: cn('kpt-date-range', isOpen && 'kpt-date-range--open', disabled && 'kpt-date-range--disabled', showInvalid && 'kpt-date-range--invalid'), role: "button", tabIndex: 0, id: field?.controlId, "aria-disabled": disabled || undefined, onClick: toggleOpen, onKeyDown: (event) => {
-                    if (event.key === 'Enter')
-                        toggleOpen();
-                }, onBlur: () => onTouch?.(), children: [display ? (_jsx("span", { className: "kpt-date-range__value", children: display })) : (_jsx("span", { className: "kpt-date-range__placeholder", children: placeholder ?? t('dateRange.placeholder') })), _jsx("span", { className: "kpt-date-range__spacer" }), display ? (_jsx("button", { type: "button", className: "kpt-date-range__clear", onClick: clear, "aria-label": t('common.clear'), children: _jsx(KptIcon, { name: "x" }) })) : null, _jsx(KptIcon, { className: "kpt-date-range__icon", name: "calendar" })] }), _jsx(KptOverlay, { open: isOpen, anchor: anchor, onClose: close, offset: 4, children: _jsx("div", { className: cn('kpt-calendar', mode === 'time' && 'kpt-calendar--clock', mode !== 'time' && 'kpt-calendar--range', multi && mode !== 'time' && 'kpt-calendar--multi'), children: mode === 'time' ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-range-tabs", children: [_jsx("button", { type: "button", className: cn(timeEnd === 'start' && 'is-active'), onClick: () => setTimeEnd('start'), children: t('dateRange.from') }), _jsx("button", { type: "button", className: cn(timeEnd === 'end' && 'is-active'), onClick: () => setTimeEnd('end'), children: t('dateRange.to') })] }), _jsx(KptClock
-                            // Klucz na edytowanym końcu wymusza remount przy przełączeniu Od/Koniec — tarcza ma
-                            // wtedy wrócić do etapu godzin, tak jak dwie osobne instancje w porcie Angulara.
-                            , { value: clockValue, onValueChange: setClockValue, hourFormat: hourFormat, minuteStep: minuteStep }, timeEnd), _jsx("div", { className: "kpt-calendar__footer", children: _jsx(KptButton, { size: "sm", onClick: commit, children: t('common.done') }) })] })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: "kpt-calendar__panels", children: panels.map((panel, index) => (_jsxs("div", { className: "kpt-calendar__panel", children: [_jsxs("div", { className: "kpt-calendar__header", children: [index === 0 ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", onClick: () => setPage(({ y, m }) => (m === 0 ? { y: y - 1, m: 11 } : { y, m: m - 1 })), "aria-label": t('datepicker.prevMonth'), children: _jsx(KptIcon, { name: "chevron-left" }) })) : (_jsx("span", { className: "kpt-calendar__nav-slot" })), _jsx("span", { className: "kpt-calendar__title", children: panel.label }), index === panels.length - 1 ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", onClick: () => setPage(({ y, m }) => (m === 11 ? { y: y + 1, m: 0 } : { y, m: m + 1 })), "aria-label": t('datepicker.nextMonth'), children: _jsx(KptIcon, { name: "chevron-right" }) })) : (_jsx("span", { className: "kpt-calendar__nav-slot" }))] }), _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: panel.weeks.flat().map((cell) => cell.blank ? (_jsx("span", { className: "kpt-calendar__day kpt-calendar__day--blank" }, cell.iso)) : (_jsx("button", { type: "button", className: cn('kpt-calendar__day', !cell.inMonth && 'kpt-calendar__day--muted', cell.today && 'kpt-calendar__day--today', cell.inRange && 'kpt-calendar__day--range', cell.rangeStart && 'kpt-calendar__day--range-start', cell.rangeEnd && 'kpt-calendar__day--range-end', (cell.isStart || cell.isEnd) && 'kpt-calendar__day--selected'), onClick: () => selectDay(cell.iso), children: cell.day }, cell.iso))) })] }, panel.key))) }), mode === 'datetime' ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-range-tabs", children: [_jsx("button", { type: "button", className: cn(timeEnd === 'start' && 'is-active'), onClick: () => setTimeEnd('start'), children: t('dateRange.fromTime') }), _jsx("button", { type: "button", className: cn(timeEnd === 'end' && 'is-active'), onClick: () => setTimeEnd('end'), children: t('dateRange.toTime') })] }), _jsx(KptClock, { value: clockValue, onValueChange: setClockValue, hourFormat: hourFormat, minuteStep: minuteStep }, timeEnd), _jsx("div", { className: "kpt-calendar__footer", children: _jsx(KptButton, { size: "sm", onClick: commit, children: t('common.done') }) })] })) : null] })) }) })] }));
+    return (_jsxs("div", { className: cn('kpt-date-range-host', className), ...rest, children: [_jsxs("div", { ref: (el) => {
+                    triggerRef.current = el;
+                    setAnchor(el);
+                }, className: cn('kpt-date-range', isOpen && 'kpt-date-range--open', disabled && 'kpt-date-range--disabled', showInvalid && 'kpt-date-range--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-invalid": showInvalid || undefined, "aria-label": ariaLabel ?? undefined, onClick: toggleOpen, onKeyDown: (event) => {
+                    if (disabled)
+                        return;
+                    if (event.key === 'Enter' || event.key === ' ' || event.key === 'ArrowDown') {
+                        event.preventDefault();
+                        if (!isOpen)
+                            toggleOpen();
+                    }
+                    else if ((event.key === 'Delete' || event.key === 'Backspace') && current.start) {
+                        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-date-range__value", children: display })) : (_jsx("span", { className: "kpt-date-range__placeholder", children: placeholder ?? t('dateRange.placeholder') })), _jsx("span", { className: "kpt-date-range__spacer" }), display ? (_jsx("button", { type: "button", className: "kpt-date-range__clear", tabIndex: -1, onClick: clear, "aria-label": t('common.clear'), children: _jsx(KptIcon, { name: "x" }) })) : null, _jsx(KptIcon, { className: "kpt-date-range__icon", name: "calendar" })] }), _jsx(KptOverlay, { open: isOpen, anchor: anchor, onClose: close, offset: 4, children: _jsxs("div", { ref: panelRef, id: panelId, role: "dialog", "aria-label": t('dateRange.dialog'), className: cn('kpt-calendar', mode === 'time' && 'kpt-calendar--clock', mode !== 'time' && 'kpt-calendar--range', multi && mode !== 'time' && 'kpt-calendar--multi'), onKeyDown: (event) => {
+                        if (event.key === 'Escape') {
+                            event.preventDefault();
+                            event.stopPropagation();
+                            closeAndFocus();
+                        }
+                        else if (event.key === 'Tab') {
+                            trapTab(event.currentTarget, event.nativeEvent);
+                        }
+                    }, children: [_jsx("span", { className: "kpt-calendar__live", "aria-live": "polite", children: announcement }), mode === 'time' ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-range-tabs", children: [_jsx("button", { type: "button", className: cn(timeEnd === 'start' && 'is-active'), onClick: () => setTimeEnd('start'), children: t('dateRange.from') }), _jsx("button", { type: "button", className: cn(timeEnd === 'end' && 'is-active'), onClick: () => setTimeEnd('end'), children: t('dateRange.to') })] }), _jsx(KptClock
+                                // Klucz na edytowanym końcu wymusza remount przy przełączeniu Od/Koniec — tarcza ma
+                                // wtedy wrócić do etapu godzin, tak jak dwie osobne instancje w porcie Angulara.
+                                , { value: clockValue, onValueChange: setClockValue, hourFormat: hourFormat, minuteStep: minuteStep }, timeEnd), _jsx("div", { className: "kpt-calendar__footer", children: _jsx(KptButton, { size: "sm", onClick: commit, children: t('common.done') }) })] })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: "kpt-calendar__panels", children: panels.map((panel, index) => (_jsxs("div", { className: "kpt-calendar__panel", children: [_jsxs("div", { className: "kpt-calendar__header", children: [index === 0 ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", onClick: () => turnPage(-1), "aria-label": t('datepicker.prevMonth'), children: _jsx(KptIcon, { name: "chevron-left" }) })) : (_jsx("span", { className: "kpt-calendar__nav-slot" })), _jsx("span", { className: "kpt-calendar__title", children: panel.label }), index === panels.length - 1 ? (_jsx("button", { type: "button", className: "kpt-calendar__nav", onClick: () => turnPage(1), "aria-label": t('datepicker.nextMonth'), children: _jsx(KptIcon, { name: "chevron-right" }) })) : (_jsx("span", { className: "kpt-calendar__nav-slot" }))] }), _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: panel.weeks.flat().map((cell) => cell.blank ? (_jsx("span", { className: "kpt-calendar__day kpt-calendar__day--blank" }, cell.iso)) : (_jsx("button", { type: "button", className: cn('kpt-calendar__day', !cell.inMonth && 'kpt-calendar__day--muted', cell.today && 'kpt-calendar__day--today', cell.inRange && 'kpt-calendar__day--range', cell.rangeStart && 'kpt-calendar__day--range-start', cell.rangeEnd && 'kpt-calendar__day--range-end', (cell.isStart || cell.isEnd) && 'kpt-calendar__day--selected'), "data-iso": cell.iso, tabIndex: cell.iso === focusIso ? 0 : -1, "aria-label": dayLabel(cell), "aria-current": cell.today ? 'date' : undefined, "aria-pressed": cell.isStart || cell.isEnd, disabled: cell.disabled, onClick: () => selectDay(cell.iso), children: cell.day }, cell.iso))) })] }, panel.key))) }), mode === 'datetime' ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-range-tabs", children: [_jsx("button", { type: "button", className: cn(timeEnd === 'start' && 'is-active'), onClick: () => setTimeEnd('start'), children: t('dateRange.fromTime') }), _jsx("button", { type: "button", className: cn(timeEnd === 'end' && 'is-active'), onClick: () => setTimeEnd('end'), children: t('dateRange.toTime') })] }), _jsx(KptClock, { value: clockValue, onValueChange: setClockValue, hourFormat: hourFormat, minuteStep: minuteStep }, timeEnd), _jsx("div", { className: "kpt-calendar__footer", children: _jsx(KptButton, { size: "sm", onClick: commit, children: t('common.done') }) })] })) : null] }))] }) })] }));
 }

package/dist/date-range/llms.txt

@@ -20,7 +20,10 @@ Import: `import { KptDateRange, type KptDateRangeValue } from '@konce-pt/react';
 - `hourFormat`: 12 | 24 (default 24); `minuteStep`: number (default 1)
 - `placeholder` — without one it falls back to `dateRange.placeholder`
 - `displayFormat`: `'pl'` (default) | `'iso'`
-- `disabled`, `invalid`, `touched`, `onTouch()`
+- `minDate`, `maxDate`: 'YYYY-MM-DD' bounds (inclusive); days outside are disabled
+- `ariaLabel` — the accessible name when no `<label for>` describes the field
+- `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
 
 ## Two clicks, one band
@@ -31,6 +34,18 @@ The panel stays open until the range closes — the second click needs somewhere
 With several panels the adjacent-month days become blank slots: otherwise the same date would be
 clickable twice, and the band would paint in both places.
 
+## Keyboard
+As in the date picker: the trigger has `aria-haspopup="dialog"` and `aria-expanded`; `Enter`, `Space`
+and `↓` open the panel (a `role="dialog"` named "Choose a date range") with focus on the range start,
+or today. The arrows, `Home`/`End` and `PageUp`/`PageDown` (with `Shift` — a year) walk the days across
+every panel, shifting the set of months when focus leaves it. `Tab` cycles inside the panel, `Escape`
+closes it, and picking the end (or "Done") returns focus to the trigger. `Delete`/`Backspace` on the
+trigger clears the range.
+
+Each day is named with the full date and its role in the range ("…, start of range", "…, end of range",
+"…, in range") — the band colour is not the only carrier. The ends have `aria-pressed`, today has
+`aria-current="date"`. After the first pick a polite live region says "Start: … Choose the end date.".
+
 ## The clock remounts when the end switches
 `key={timeEnd}` on `KptClock`, so the dial returns to the hours stage after the From/To toggle —
 in Angular that came for free from two separate template branches.
@@ -45,10 +60,18 @@ in Angular that came for free from two separate template branches.
 Day and month names come from `Intl`; "From/To", the navigation, "Done" and the placeholder come
 from the `dateRange`, `datepicker` and `common` namespaces.
 
+## 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
 The field `--kpt-form-field-*`; the calendar `--kpt-color-surface-raised`, the range
 `--kpt-color-primary`.
 
 ## Accessibility
-The trigger is `role="button"` with Enter support; the days are real buttons, and the time ends are
-switched with a two-button toggle rather than a custom control.
+The trigger is `role="button"` with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`;
+the panel is a named `role="dialog"`; the days are real buttons named with the date and their range
+role, and the time ends are switched with a two-button toggle rather than a custom control. The
+keyboard is described above.