@konce-pt/react 0.11.1 → 0.12.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";
@@ -21,18 +22,20 @@ const EMPTY_RANGE = { start: '', end: '' };
  * 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`.
+ * 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. */
     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);
@@ -41,10 +44,14 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
     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('');
@@ -54,7 +61,7 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
     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' });
@@ -75,7 +82,7 @@ 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;
@@ -86,38 +93,47 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
         }
         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
-            ? `${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 = () => {
@@ -132,15 +148,13 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
         triggerRef.current?.focus();
     };
     // 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);
-    });
+    }, [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);
@@ -154,19 +168,24 @@ 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ą. */
     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.
@@ -194,6 +213,7 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
                 hideOutside: multi,
                 minDate,
                 maxDate,
+                firstDay,
             }),
         };
     });
@@ -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();
@@ -255,7 +278,7 @@ export function KptDateRange({ value, defaultValue = EMPTY_RANGE, onValueChange,
                     }
                 }, 
                 // 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) => {
+                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();

package/dist/date-range/llms.txt

@@ -5,7 +5,7 @@ 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">
+      <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>
@@ -19,7 +19,7 @@ Import: `import { KptDateRange, type KptDateRangeValue } from '@konce-pt/react';
 - `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'`
+- `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
 - `disabled`, `invalid`, `touched`
@@ -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,7 +15,13 @@ 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ł. */
@@ -26,6 +32,10 @@ export interface KptDatepickerProps extends Omit<ComponentPropsWithRef<'div'>, '
     /** 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;
@@ -41,8 +51,12 @@ export interface KptDatepickerProps extends Omit<ComponentPropsWithRef<'div'>, '
  * 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;