@konce-pt/react 0.11.2 → 0.14.0

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

@@ -1,6 +1,7 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-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 { useEffect, useEffectEvent, useRef, useState, } from 'react';
+import { buildRangeGrid, clampVisibleMonths, datePart, dayPeriodLabels, displayDate, formatTime, kptFirstDayOfWeek, orderWeekdays, 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";
@@ -18,43 +19,49 @@ const EMPTY_RANGE = { start: '', end: '' };
  * `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
+ * Klawiatura jak w `KptDatepicker`: `Enter`/`Spacja`/`ArrowDown` 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`.
+ * Krańce i środek zakresu są w nazwie dnia ("..., początek zakresu"), a wybór i przewinięcie miesiąca
+ * ogłasza region `polite`. Pole to `role="combobox"` z `aria-haspopup="dialog"`, więc niesie
+ * `aria-required`, `aria-readonly` i `aria-invalid`. Tydzień zaczyna się wg aktywnego języka.
  *
  * @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', minDate = null, maxDate = null, ariaLabel = null, id, 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', firstDayOfWeek = null, open, onOpenChange, minDate = null, maxDate = null, ariaLabel = null, id, disabled = false, readOnly = false, required = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
     const { t, locale: activeLocale } = useKptMessages({ locale, dictionary });
-    /** `div` z rolą nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
+    /** `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 [isOpen, setOpen] = useControllableState({ value: open, defaultValue: false, onChange: onOpenChange });
     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). */
+    /** 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;
+    /** Prośba o przeniesienie fokusu po najbliższym renderze (otwarcie, ruch klawiszem) - licznik w stanie. */
+    const [focusRequest, setFocusRequest] = useState(0);
+    const requestFocus = () => setFocusRequest((n) => n + 1);
+    /** "Dziś" liczone przy każdym otwarciu - panel otwarty po północy nie pokazuje wczorajszego dnia. */
+    const [today, setToday] = useState(() => new Date());
     const todayIso = toIso(today);
+    const firstDay = firstDayOfWeek ?? kptFirstDayOfWeek(activeLocale);
+    const periods = dayPeriodLabels(activeLocale);
     const showInvalid = invalid && (touched ?? true);
     const [page, setPage] = useState(() => ({ y: today.getFullYear(), m: today.getMonth() }));
     const [startTime, setStartTime] = useState('');
     const [endTime, setEndTime] = useState('');
     const [timeEnd, setTimeEnd] = useState('start');
-    // Część kalendarzowa zakresu w trybie datetime — wartość powstaje dopiero przy „Gotowe".
+    // Część kalendarzowa zakresu w trybie datetime - wartość powstaje dopiero przy "Gotowe".
     const [startDate, setStartDate] = useState('');
     const [endDate, setEndDate] = useState('');
     const months = monthNames(activeLocale);
-    const weekdays = weekdayNames(activeLocale);
+    const weekdays = orderWeekdays(weekdayNames(activeLocale), firstDay);
     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' });
@@ -62,7 +69,7 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
         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. */
+    /** 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)
@@ -75,49 +82,58 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
     };
     const fmtTime = (hhmm) => {
         const parsed = parseTime(hhmm);
-        return parsed ? formatTime(parsed.h, parsed.m, hourFormat) : '';
+        return parsed ? formatTime(parsed.h, parsed.m, hourFormat, periods) : '';
     };
     const display = (() => {
         const { start, end } = current;
         if (!start)
             return '';
         if (mode === 'time') {
-            return end ? `${fmtTime(start)} – ${fmtTime(end)}` : `${fmtTime(start)} – …`;
+            return end ? `${fmtTime(start)} - ${fmtTime(end)}` : `${fmtTime(start)} - ...`;
         }
         if (mode === 'datetime') {
             const one = (v) => {
-                const date = formatDate(datePart(v), displayFormat);
+                const date = displayDate(datePart(v), displayFormat, activeLocale);
                 const time = fmtTime(timePart(v));
                 return time ? `${date} ${time}` : date;
             };
-            return end ? `${one(start)} – ${one(end)}` : `${one(start)} – …`;
+            return end ? `${one(start)} - ${one(end)}` : `${one(start)} - ...`;
         }
-        return end
-            ? `${formatDate(start, displayFormat)} – ${formatDate(end, displayFormat)}`
-            : `${formatDate(start, displayFormat)} – …`;
+        const fmt = (iso) => displayDate(iso, displayFormat, activeLocale);
+        return end ? `${fmt(start)} - ${fmt(end)}` : `${fmt(start)} - ...`;
     })();
+    // Panel otwiera też `open` z zewnątrz - stan początkowy liczymy przy każdym przejściu w stan
+    // otwarty, wzorcem "poprzednia wartość w stanie" (bez efektu i klatki ze starym widokiem).
+    const [wasOpen, setWasOpen] = useState(isOpen);
+    if (wasOpen !== isOpen) {
+        setWasOpen(isOpen);
+        if (isOpen)
+            prepareOpen();
+    }
+    function prepareOpen() {
+        const now = new Date();
+        setToday(now);
+        const { start, end } = current;
+        const focus = initialFocusDate(datePart(start), toIso(now), minDate, maxDate);
+        setFocusIso(focus);
+        setAnnouncement('');
+        setPage({ y: +focus.slice(0, 4), m: +focus.slice(5, 7) - 1 });
+        requestFocus();
+        if (mode === 'datetime') {
+            setStartDate(datePart(start));
+            setEndDate(datePart(end));
+            setStartTime(timePart(start) || '00:00');
+            setEndTime(timePart(end) || '00:00');
+        }
+        else if (mode === 'time') {
+            setStartTime(/^\d{2}:\d{2}$/.test(start) ? start : '00:00');
+            setEndTime(/^\d{2}:\d{2}$/.test(end) ? end : '00:00');
+        }
+        setTimeEnd('start');
+    }
     const toggleOpen = () => {
-        if (disabled)
+        if (disabled || readOnly)
             return;
-        if (!isOpen) {
-            const { start, end } = current;
-            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));
-                setStartTime(timePart(start) || '00:00');
-                setEndTime(timePart(end) || '00:00');
-            }
-            else if (mode === 'time') {
-                setStartTime(/^\d{2}:\d{2}$/.test(start) ? start : '00:00');
-                setEndTime(/^\d{2}:\d{2}$/.test(end) ? end : '00:00');
-            }
-            setTimeEnd('start');
-        }
         setOpen(!isOpen);
     };
     const close = () => {
@@ -126,22 +142,20 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
         setOpen(false);
         onTouch?.();
     };
-    /** Zamknięcie z powrotem fokusu na pole — po wyborze z klawiatury, `Escape`. */
+    /** 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.
+    // Fokus po renderze. Panel w nakładce jest niewidoczny do pierwszego pomiaru - stąd rAF.
+    const focusActive = useEffectEvent(() => focusCalendarActive(panelRef.current, focusIso));
     useEffect(() => {
-        if (!isOpen || !wantFocus.current)
+        if (!isOpen || focusRequest === 0)
             return;
-        const frame = requestAnimationFrame(() => {
-            wantFocus.current = false;
-            focusCalendarActive(panelRef.current, focusIso);
-        });
+        const frame = requestAnimationFrame(() => focusActive());
         return () => cancelAnimationFrame(frame);
-    });
-    /** Przesuwa okno paneli tak, żeby miesiąc dnia `iso` był widoczny — z najmniejszym skokiem. */
+    }, [focusRequest, isOpen]);
+    /** 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;
@@ -154,22 +168,27 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
     };
     const onDayKeyDown = (event) => {
         const rtl = !!panelRef.current && getComputedStyle(panelRef.current).direction === 'rtl';
-        const next = moveFocusDate(focusIso, event.key, { shift: event.shiftKey, rtl, minDate, maxDate });
+        const next = moveFocusDate(focusIso, event.key, { shift: event.shiftKey, rtl, minDate, maxDate, firstDay });
         if (next === null)
             return;
         event.preventDefault();
         setFocusIso(next);
         revealMonth(next);
-        wantFocus.current = true;
+        requestFocus();
     };
-    /** Strzałki ‹ ›: fokus zostaje na strzałce, ale przystanek siatki idzie za stroną. */
+    /** 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 });
+        // Przewinięcie ogłasza widoczne miesiące (APG: `aria-live` na nagłówku).
+        setAnnouncement(Array.from({ length: panelCount }, (_, i) => {
+            const month = first + i;
+            return `${months[((month % 12) + 12) % 12]} ${Math.floor(month / 12)}`;
+        }).join(' - '));
+        const moved = moveFocusDate(focusIso, dir === 1 ? 'PageDown' : 'PageUp', { minDate, maxDate, firstDay });
         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.
+            // Nowe okno zaczyna się od `first` - dzień spoza niego nie dostałby przystanku Tab.
             if (target >= first && target < first + panelCount)
                 setFocusIso(moved);
         }
@@ -194,6 +213,7 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
                 hideOutside: multi,
                 minDate,
                 maxDate,
+                firstDay,
             }),
         };
     });
@@ -204,12 +224,12 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
             setStartDate(next.start);
             setEndDate(next.end);
             announce(next.start, next.end);
-            return; // czas do wyboru → zamknięcie przez „Gotowe"
+            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ść.
+        // Panel zostaje otwarty do czasu domknięcia zakresu - inaczej drugi klik nie miałby gdzie paść.
         if (next.end)
             closeAndFocus();
     };
@@ -232,17 +252,20 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
     };
     const clear = (event) => {
         event.stopPropagation();
+        if (readOnly)
+            return;
         setCurrent(EMPTY_RANGE);
         setStartDate('');
         setEndDate('');
+        onTouch?.();
     };
     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: (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)
+                }, className: cn('kpt-date-range', isOpen && 'kpt-date-range--open', disabled && 'kpt-date-range--disabled', readOnly && 'kpt-date-range--readonly', showInvalid && 'kpt-date-range--invalid'), role: "combobox", tabIndex: 0, "aria-keyshortcuts": "Delete Backspace", "aria-required": required || undefined, "aria-readonly": readOnly || undefined, "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 || readOnly)
                         return;
                     if (event.key === 'Enter' || event.key === ' ' || event.key === 'ArrowDown') {
                         event.preventDefault();
@@ -254,8 +277,8 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
                         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) => {
+                // 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 && !readOnly ? (_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();
@@ -265,7 +288,7 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
                             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
+                                // 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

@@ -5,49 +5,49 @@ Import: `import { KptDateRange, type KptDateRangeValue } from '@konce-pt/react';
 
 ## DOM
     <div class="kpt-date-range-host">
-      <div class="kpt-date-range" role="button" tabindex="0">
-        <span class="kpt-date-range__value">08.09.2026 – 14.09.2026</span>
-        …clear, icon…
+      <div class="kpt-date-range" role="combobox" tabindex="0" aria-haspopup="dialog">
+        <span class="kpt-date-range__value">08.09.2026 - 14.09.2026</span>
+        ...clear, icon...
       </div>
     </div>
-    <!-- in a portal: <div class="kpt-calendar kpt-calendar--range kpt-calendar--multi">…</div> -->
+    <!-- in a portal: <div class="kpt-calendar kpt-calendar--range kpt-calendar--multi">...</div> -->
 
 ## Props
-- `value` / `defaultValue` / `onValueChange` — `{ start, end }`: dates 'YYYY-MM-DD',
+- `value` / `defaultValue` / `onValueChange` - `{ start, end }`: dates 'YYYY-MM-DD',
   datetime 'YYYY-MM-DDTHH:mm', times 'HH:mm'
 - `mode`: `'date'` (default) | `'datetime'` | `'time'`
-- `visibleMonths`: number (default 1, clamped to 1–3) — months side by side; ignored in 'time' mode
+- `visibleMonths`: number (default 1, clamped to 1-3) - months side by side; ignored in 'time' mode
 - `hourFormat`: 12 | 24 (default 24); `minuteStep`: number (default 1)
-- `placeholder` — without one it falls back to `dateRange.placeholder`
-- `displayFormat`: `'pl'` (default) | `'iso'`
+- `placeholder` - without one it falls back to `dateRange.placeholder`
+- `displayFormat`: `'pl'` (default) | `'iso'` | `'locale'`
 - `minDate`, `maxDate`: 'YYYY-MM-DD' bounds (inclusive); days outside are disabled
-- `ariaLabel` — the accessible name when no `<label for>` describes the field
+- `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
+- `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
 The first click sets `start`, the second `end`, a third starts over; clicking before the start
 normalizes the order rather than producing a reversed range (`pickRangeDay` in `@konce-pt/datetime`).
-The panel stays open until the range closes — the second click needs somewhere to land.
+The panel stays open until the range closes - the second click needs somewhere to land.
 
 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
+and `ArrowDown` 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.".
+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 —
+`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.
 
 ## Examples
@@ -60,6 +60,20 @@ 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.
 
+## Week start, display format and field state
+- The week starts by the active language (`Intl.Locale#getWeekInfo`, with a fallback list of regions):
+  en / en-US on Sunday, pl, de, en-GB on Monday. `firstDayOfWeek` (1 = Monday ... 7 = Sunday) overrides it;
+  the headers, the grid and `Home`/`End` follow it.
+- `displayFormat`: `'pl'` (DD.MM.YYYY, default), `'iso'` (YYYY-MM-DD) or `'locale'` - order and separators
+  from `Intl` (en-US: MM/DD/YYYY). The placeholder follows the format and its letters follow the language
+  (EN `YYYY`, PL `RRRR`, the `datepicker.yearToken`/`monthToken`/`dayToken` keys). AM/PM come from `Intl`.
+- The field is `role="combobox"` with `aria-haspopup="dialog"` (the APG select-only combobox), so it carries
+  `aria-required` (`required`), `aria-readonly` (`readOnly` - the value shows, the panel does not open,
+  there is no clear button) and `aria-invalid`.
+- Turning the page with < > is announced (`aria-live="polite"`); the title buttons are named
+  "October, Choose month" - the visible text first (WCAG 2.5.3). Clearing the value counts as a touch.
+- "Today" is computed on every open, so a panel opened after midnight marks the right day.
+
 ## 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
@@ -71,7 +85,7 @@ The field `--kpt-form-field-*`; the calendar `--kpt-color-surface-raised`, the r
 `--kpt-color-primary`.
 
 ## Accessibility
-The trigger is `role="button"` with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`;
+The trigger is `role="combobox"` 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.

package/dist/datepicker/datepicker.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentPropsWithRef } from 'react';
-import { type KptCalendarView, type KptDateSelectionMode } from '@konce-pt/datetime';
+import { type KptCalendarView, type KptDateDisplayFormat, type KptDateSelectionMode, type KptFirstDayOfWeek } from '@konce-pt/datetime';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export type { KptDateSelectionMode as KptDatepickerMode, KptCalendarView as KptDatepickerView };
 export interface KptDatepickerProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'>, KptI18nOverrides {
@@ -15,34 +15,48 @@ export interface KptDatepickerProps extends Omit<ComponentPropsWithRef<'div'>, '
     placeholder?: string;
     /** Prezentacja miesiąca w trybie 'month' i w etykietach: słownie czy liczbą. */
     monthDisplay?: 'long' | 'number';
-    displayFormat?: 'pl' | 'iso';
+    /**
+     * Zapis daty: `'pl'` (DD.MM.RRRR, domyślnie), `'iso'` albo `'locale'` - kolejność i separatory
+     * z `Intl` dla aktywnego języka. Placeholder idzie za formatem, a jego litery za językiem.
+     */
+    displayFormat?: KptDateDisplayFormat;
+    /** Pierwszy dzień tygodnia (1 = poniedziałek ... 7 = niedziela); `null` = wg aktywnego języka. */
+    firstDayOfWeek?: KptFirstDayOfWeek | null;
     hourFormat?: 12 | 24;
     minuteStep?: number;
-    /** Stan panelu — pozwala otworzyć kalendarz z zewnątrz i wiedzieć, kiedy wybór się skończył. */
+    /** Stan panelu - pozwala otworzyć kalendarz z zewnątrz i wiedzieć, kiedy wybór się skończył. */
     open?: boolean;
     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 pola (nie hosta); bez niego generowane, w `KptFormField` - z wrappera. */
     id?: string;
     disabled?: boolean;
+    /** Tylko do odczytu - wartość widać, panel się nie otwiera (`aria-readonly`). */
+    readOnly?: boolean;
+    /** Pole wymagane - `aria-required`. */
+    required?: boolean;
     invalid?: boolean;
     touched?: boolean;
     onTouch?: () => void;
 }
 /**
  * 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.
+ * 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ą
+ * Klawiatura według wzorca WAI-ARIA "date picker dialog": `Enter`/`Spacja`/`ArrowDown` 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
+ * (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ść.
  *
+ * Pole to `role="combobox"` z `aria-haspopup="dialog"`, więc niesie `aria-required`,
+ * `aria-readonly` i `aria-invalid`. Tydzień zaczyna się wg aktywnego języka, chyba że podano
+ * `firstDayOfWeek`; przewinięcie strony strzałką < > jest ogłaszane.
+ *
  * @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, id, 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, firstDayOfWeek, hourFormat, minuteStep, open, onOpenChange, ariaLabel, id, disabled, readOnly, required, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptDatepickerProps>): import("react").JSX.Element;