@konce-pt/react 0.11.1 → 0.12.0

package/dist/internal/use-controllable-state.js

@@ -1,18 +1,39 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { isDevBuild } from "./dev.js";
 /**
  * Stan działający w obu trybach naraz: kontrolowanym (`value` podane z zewnątrz)
  * i niekontrolowanym (`defaultValue` + stan wewnętrzny). Kontrakt jest ten sam
  * co w natywnych polach formularza, więc komponenty współpracują z natywnym
  * `<form>`, React 19 Actions i React Hook Form bez adapterów.
+ *
+ * `setValue` ma stałą tożsamość: rodzic przekazujący `onChange` jako funkcję inline nie restartuje
+ * efektów, które mają `setValue` w zależnościach. Przejście między trybami (`value` raz podane,
+ * raz `undefined`) działa jak w Reakcie — po cichu przełącza źródło — ale w buildzie deweloperskim
+ * ostrzega, tak jak React robi to dla `<input>`.
  */
 export function useControllableState(options) {
     const { value, defaultValue, onChange } = options;
     const isControlled = value !== undefined;
     const [uncontrolled, setUncontrolled] = useState(defaultValue);
+    // Najświeższy tryb i callback dla stabilnego `setValue` — odświeżane po zatwierdzeniu renderu.
+    const latest = useRef({ isControlled, onChange });
+    useLayoutEffect(() => {
+        latest.current = { isControlled, onChange };
+    });
     const setValue = useCallback((next) => {
-        if (!isControlled)
+        if (!latest.current.isControlled)
             setUncontrolled(next);
-        onChange?.(next);
-    }, [isControlled, onChange]);
+        latest.current.onChange?.(next);
+    }, []);
+    const [initiallyControlled] = useState(isControlled);
+    const warned = useRef(false);
+    useEffect(() => {
+        if (warned.current || isControlled === initiallyControlled || !isDevBuild())
+            return;
+        warned.current = true;
+        console.warn(isControlled
+            ? '[koncept-ui] Komponent przeszedł z trybu niekontrolowanego w kontrolowany (`value` było undefined). Wybierz jeden tryb na całe życie komponentu.'
+            : '[koncept-ui] Komponent przeszedł z trybu kontrolowanego w niekontrolowany (`value` stało się undefined). Do „braku wartości” użyj null, nie undefined.');
+    }, [isControlled, initiallyControlled]);
     return [isControlled ? value : uncontrolled, setValue];
 }

package/dist/internal/use-modal-focus.d.ts

@@ -4,6 +4,7 @@ import { type RefObject } from 'react';
  * z fokusem, przenosi fokus do panelu (pierwszy element z kolejki Tab albo sam panel) i zawija
  * `Tab` / `Shift+Tab` w jego obrębie; przy zamknięciu oddaje fokus zapamiętanemu elementowi.
  * Bez tego `aria-modal="true"` obiecywał czytnikowi okno, z którego Tab po cichu wychodził.
+ * Otwarty panel blokuje też przewijanie strony pod spodem (wspólny licznik z `KptDialog`).
  *
  * Port Angulara robi to samo na pułapce CDK (`shared/modal-focus.ts`) — zmiana zachowania w obu.
  */

package/dist/internal/use-modal-focus.js

@@ -1,4 +1,10 @@
 import { useEffect } from 'react';
+import { kptLockScroll } from "./scroll-lock.js";
+/**
+ * Stos otwartych paneli modalnych. Pułapki słuchają `keydown` na dokumencie, więc przy dwóch
+ * otwartych naraz (szuflada → dialog) walczyłyby o ten sam Tab — klawisz obsługuje tylko najwyższa.
+ */
+const stack = [];
 /** Elementy z kolejki Tab — na nich zawija się pułapka. */
 const TABBABLE = 'a[href], button:not(:disabled), input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])';
 function tabbables(panel) {
@@ -9,6 +15,7 @@ function tabbables(panel) {
  * z fokusem, przenosi fokus do panelu (pierwszy element z kolejki Tab albo sam panel) i zawija
  * `Tab` / `Shift+Tab` w jego obrębie; przy zamknięciu oddaje fokus zapamiętanemu elementowi.
  * Bez tego `aria-modal="true"` obiecywał czytnikowi okno, z którego Tab po cichu wychodził.
+ * Otwarty panel blokuje też przewijanie strony pod spodem (wspólny licznik z `KptDialog`).
  *
  * Port Angulara robi to samo na pułapce CDK (`shared/modal-focus.ts`) — zmiana zachowania w obu.
  */
@@ -19,6 +26,8 @@ export function useModalFocus(open, panelRef) {
             return;
         const active = document.activeElement;
         const returnTo = active instanceof HTMLElement && !panel.contains(active) ? active : null;
+        stack.push(panel);
+        const releaseScroll = kptLockScroll();
         // Klatkę później: panel dostaje `is-open` (i `visibility: visible`) w tym samym commicie,
         // a przeglądarka nie skupi elementu, który w chwili wywołania jest jeszcze niewidoczny.
         const frame = requestAnimationFrame(() => {
@@ -26,7 +35,7 @@ export function useModalFocus(open, panelRef) {
             (first ?? panel).focus();
         });
         const onKeyDown = (event) => {
-            if (event.key !== 'Tab')
+            if (event.key !== 'Tab' || stack[stack.length - 1] !== panel)
                 return;
             const items = tabbables(panel);
             if (!items.length) {
@@ -50,6 +59,8 @@ export function useModalFocus(open, panelRef) {
         return () => {
             cancelAnimationFrame(frame);
             document.removeEventListener('keydown', onKeyDown);
+            stack.splice(stack.indexOf(panel), 1);
+            releaseScroll();
             if (returnTo?.isConnected)
                 returnTo.focus();
         };

package/dist/knob/knob.d.ts

@@ -18,6 +18,8 @@ export interface KptKnobProps extends Omit<ComponentPropsWithRef<'div'>, 'onChan
     /** Nazwa dostępna, gdy kontrolki nie opisuje etykieta (`<label for>` albo `KptFormField`). */
     ariaLabel?: string | null;
     disabled?: boolean;
+    /** Tylko do odczytu — pokrętło widać i da się na nim stanąć, ale nie zmienić wartości. */
+    readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
     onTouch?: () => void;
@@ -26,10 +28,11 @@ export interface KptKnobProps extends Omit<ComponentPropsWithRef<'div'>, 'onChan
  * Pokrętło — wybór wartości po łuku, przeciąganiem albo strzałkami.
  *
  * Skok wartości (strzałka, `Home`/`End`, klik w łuk, zmiana z zewnątrz) łuk i licznik pokonują
- * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `prefers-reduced-motion` wyłącza
+ * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `PageUp`/`PageDown` skaczą o dziesięć
+ * kroków, a wartości leżą na siatce `min + k·step` dla myszy i klawiatury. `prefers-reduced-motion` wyłącza
  * animację, a `aria-valuenow` zawsze niesie wartość docelową, nie pośrednią.
  *
  * @example
  * <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
  */
-export declare function KptKnob({ value, defaultValue, onValueChange, min, max, step, size, stroke, suffix, showValue, id, ariaLabel, disabled, invalid, touched, onTouch, className, ...rest }: Readonly<KptKnobProps>): import("react").JSX.Element;
+export declare function KptKnob({ value, defaultValue, onValueChange, min, max, step, size, stroke, suffix, showValue, id, ariaLabel, disabled, readOnly, invalid, touched, onTouch, className, ...rest }: Readonly<KptKnobProps>): import("react").JSX.Element;

package/dist/knob/knob.js

@@ -1,6 +1,8 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
+import { kptSnapToStep } from "../internal/step.js";
 import { kptStepDecimals, kptTween } from "../internal/tween.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptFieldA11y } from "../form-field/form-field-context.js";
@@ -15,13 +17,14 @@ const TWEEN_MS = 220;
  * Pokrętło — wybór wartości po łuku, przeciąganiem albo strzałkami.
  *
  * Skok wartości (strzałka, `Home`/`End`, klik w łuk, zmiana z zewnątrz) łuk i licznik pokonują
- * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `prefers-reduced-motion` wyłącza
+ * płynnie; przy przeciąganiu idą za kursorem bez opóźnienia. `PageUp`/`PageDown` skaczą o dziesięć
+ * kroków, a wartości leżą na siatce `min + k·step` dla myszy i klawiatury. `prefers-reduced-motion` wyłącza
  * animację, a `aria-valuenow` zawsze niesie wartość docelową, nie pośrednią.
  *
  * @example
  * <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
  */
-export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max = 100, step = 1, size = 96, stroke = 10, suffix = '', showValue = true, id, ariaLabel = null, disabled = false, invalid = false, touched, onTouch, className, ...rest }) {
+export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max = 100, step = 1, size = 96, stroke = 10, suffix = '', showValue = true, id, ariaLabel = null, disabled = false, readOnly = false, invalid = false, touched, onTouch, className, ...rest }) {
     const field = useKptFieldA11y(id, 'kpt-knob');
     const svgRef = useRef(null);
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
@@ -58,7 +61,6 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
             return `M ${x0} ${y0}`;
         return `M ${x0} ${y0} A ${r} ${r} 0 ${a1 - a0 > Math.PI ? 1 : 0} 1 ${x1} ${y1}`;
     };
-    const clamp = (raw) => Math.min(max, Math.max(min, Math.round(raw / step) * step));
     const setFromPoint = (clientX, clientY) => {
         const svg = svgRef.current;
         if (!svg)
@@ -72,10 +74,10 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
         // inaczej przeciągnięcie przez dół przeskakiwałoby z maksimum na minimum.
         if (angle > SWEEP + GAP)
             angle = angle > SWEEP + GAP / 2 ? 0 : SWEEP;
-        setCurrent(clamp(min + Math.min(1, Math.max(0, angle / SWEEP)) * range));
+        setCurrent(kptSnapToStep(min + Math.min(1, Math.max(0, angle / SWEEP)) * range, min, max, step));
     };
     const onPointerDown = (event) => {
-        if (disabled)
+        if (disabled || readOnly)
             return;
         // Bez tego przeciąganie zaznacza tekst: licznik w środku i — przez SVG — całe koło, jak po
         // `Ctrl+A`. Zablokowanie domyślnej akcji zabiera też fokus, więc oddajemy go ręcznie.
@@ -101,22 +103,21 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
         window.addEventListener('pointercancel', up);
     };
     const onKeyDown = (event) => {
-        if (disabled)
+        if (disabled || readOnly)
             return;
-        let next = current;
-        if (event.key === 'ArrowUp' || event.key === 'ArrowRight')
-            next += step;
-        else if (event.key === 'ArrowDown' || event.key === 'ArrowLeft')
-            next -= step;
-        else if (event.key === 'Home')
+        const steps = { ArrowUp: 1, ArrowRight: 1, ArrowDown: -1, ArrowLeft: -1, PageUp: 10, PageDown: -10 };
+        let next;
+        if (event.key === 'Home')
             next = min;
         else if (event.key === 'End')
             next = max;
+        else if (steps[event.key] !== undefined)
+            next = current + steps[event.key] * step;
         else
             return;
         event.preventDefault();
-        setCurrent(Math.min(max, Math.max(min, next)));
+        setCurrent(kptSnapToStep(next, min, max, step));
         onTouch?.();
     };
-    return (_jsx("div", { className: cn('kpt-knob-host', className), ...rest, children: _jsx("div", { className: cn('kpt-knob', showInvalid && 'kpt-knob--invalid'), role: "slider", id: field.id, tabIndex: disabled ? -1 : 0, "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": current, "aria-valuetext": suffix ? `${current}${suffix}` : undefined, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onPointerDown: onPointerDown, onKeyDown: onKeyDown, children: _jsxs("svg", { ref: svgRef, viewBox: `0 0 ${size} ${size}`, style: { width: size, height: size }, children: [_jsx("path", { className: "kpt-knob__range", d: arc(0, 1), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), _jsx("path", { className: "kpt-knob__value", d: arc(0, ratio), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), showValue ? (_jsxs("text", { className: "kpt-knob__text", x: size / 2, y: size / 2, textAnchor: "middle", dominantBaseline: "central", children: [shown.toFixed(kptStepDecimals(step)), suffix] })) : null] }) }) }));
+    return (_jsx("div", { className: cn('kpt-knob-host', className), ...rest, children: _jsx("div", { className: cn('kpt-knob', showInvalid && 'kpt-knob--invalid'), role: "slider", id: field.id, tabIndex: disabled ? -1 : 0, "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": current, "aria-valuetext": suffix ? `${current}${suffix}` : undefined, "aria-disabled": disabled || undefined, "aria-readonly": readOnly || undefined, "aria-invalid": showInvalid || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onPointerDown: onPointerDown, onKeyDown: onKeyDown, children: _jsxs("svg", { ref: svgRef, viewBox: `0 0 ${size} ${size}`, style: { width: size, height: size }, children: [_jsx("path", { className: "kpt-knob__range", d: arc(0, 1), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), _jsx("path", { className: "kpt-knob__value", d: arc(0, ratio), fill: "none", strokeWidth: stroke, strokeLinecap: "round" }), showValue ? (_jsxs("text", { className: "kpt-knob__text", x: size / 2, y: size / 2, textAnchor: "middle", dominantBaseline: "central", children: [shown.toFixed(kptStepDecimals(step)), suffix] })) : null] }) }) }));
 }

package/dist/knob/llms.txt

@@ -19,7 +19,8 @@ Import: `import { KptKnob } from '@konce-pt/react';`
 - `min` (0), `max` (100), `step` (1)
 - `size`: px (96) — the side of the SVG square; `stroke`: px (10) — arc thickness
 - `suffix`: string appended to the value in the middle; `showValue`: boolean (default true)
-- `disabled`, `invalid`, `touched`, `onTouch()`
+- `disabled`, `readOnly`, `invalid`, `touched`, `onTouch()` — `readOnly` keeps the knob focusable but ignores
+  the pointer and the keys (`aria-readonly`)
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The gap at the bottom
@@ -57,5 +58,6 @@ select the number or the arc.
 
 ## Accessibility
 `role="slider"` with `aria-valuemin` / `aria-valuemax` / `aria-valuenow`; arrows step by `step`,
-Home and End jump to the bounds. `disabled` sets `aria-disabled` and drops the knob out of the
+PageUp/PageDown by ten steps, Home and End jump to the bounds. Values sit on the grid `min + k·step` for
+both the pointer and the keys — with `min={1} step={2}` that is 1, 3, 5…. `disabled` sets `aria-disabled` and drops the knob out of the
 tab order.

package/dist/listbox/listbox.d.ts

@@ -16,6 +16,8 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
     /** Oznacza listę jako wymaganą atrybutem `aria-required`. */
     required?: boolean;
     disabled?: boolean;
+    /** Tylko do odczytu — po liście da się chodzić i czytać wybór, ale nie da się go zmienić. */
+    readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
     onTouch?: () => void;
@@ -37,4 +39,4 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
  * <KptListbox options={roles} value={role} onValueChange={setRole} filter />
  * <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
  */
-export declare function KptListbox<T>({ options, value, defaultValue, onValueChange, multiple, filter, id, ariaLabel, required, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptListboxProps<T>>): import("react").JSX.Element;
+export declare function KptListbox<T>({ options, value, defaultValue, onValueChange, multiple, filter, id, ariaLabel, required, disabled, readOnly, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptListboxProps<T>>): import("react").JSX.Element;

package/dist/listbox/listbox.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { foldMentionText } from '@konce-pt/mention';
@@ -24,7 +25,7 @@ import { KptIcon } from "../icon/icon.js";
  * <KptListbox options={roles} value={role} onValueChange={setRole} filter />
  * <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
  */
-export function KptListbox({ options = [], value, defaultValue = null, onValueChange, multiple = false, filter = false, id, ariaLabel = null, required = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptListbox({ options = [], value, defaultValue = null, onValueChange, multiple = false, filter = false, id, ariaLabel = null, required = false, disabled = false, readOnly = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     /** `div` z rolą nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
     const field = useKptFieldA11y(id, 'kpt-listbox');
@@ -55,18 +56,33 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
     const isSelected = (candidate) => multiple ? Array.isArray(current) && current.includes(candidate) : current === candidate;
     const toggle = (candidate) => {
         if (multiple) {
-            const list = Array.isArray(current) ? current : [];
+            const list = Array.isArray(current) ? (current) : [];
             setCurrent(list.includes(candidate) ? list.filter((item) => item !== candidate) : [...list, candidate]);
         }
         else {
             setCurrent(current === candidate ? null : candidate);
         }
     };
-    const pick = (index) => {
+    /** Ostatnio kliknięta opcja — początek zakresu dla `Shift+klik` w trybie `multiple`. */
+    const anchorIndex = useRef(-1);
+    const pick = (index, extend = false) => {
         const option = visible[index];
-        if (!option || disabledMap[index])
+        if (!option || disabledMap[index] || readOnly)
             return;
         setActiveIndex(index);
+        if (extend && multiple && anchorIndex.current >= 0) {
+            // Zaznacza (dokłada) dozwolone opcje między kotwicą a klikniętą — `Shift+klik` (APG).
+            const [lo, hi] = anchorIndex.current <= index ? [anchorIndex.current, index] : [index, anchorIndex.current];
+            const list = Array.isArray(current) ? current : [];
+            const add = visible
+                .slice(lo, hi + 1)
+                .filter((_, offset) => !disabledMap[lo + offset])
+                .map((item) => item.value)
+                .filter((item) => !list.includes(item));
+            setCurrent([...list, ...add]);
+            return;
+        }
+        anchorIndex.current = index;
         toggle(option.value);
     };
     /** Wejście fokusem: aktywna zostaje wybrana opcja, a bez niej pierwsza dozwolona. */
@@ -88,8 +104,12 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
         if (OPTION_NAV_KEYS.has(event.key)) {
             event.preventDefault();
             const next = nextOptionIndex(disabledMap, activeIndex, event.key);
-            if (next !== null)
-                setActiveIndex(next);
+            if (next === null)
+                return;
+            setActiveIndex(next);
+            // `Shift+strzałka` w wyborze wielokrotnym zaznacza opcję, na którą przeszedł fokus (APG listbox).
+            if (event.shiftKey && multiple && !readOnly && !isSelected(visible[next].value))
+                toggle(visible[next].value);
             return;
         }
         if (event.key === ' ' || event.key === 'Enter') {
@@ -99,10 +119,10 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
             pick(activeIndex);
             return;
         }
-        if (multiple && (event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'a') {
+        if (multiple && !readOnly && (event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'a') {
             event.preventDefault();
             const all = visible.filter((_, index) => !disabledMap[index]).map((option) => option.value);
-            const list = Array.isArray(current) ? current : [];
+            const list = Array.isArray(current) ? (current) : [];
             // Drugi raz `Ctrl+A` przy wszystkich zaznaczonych — odznacza widoczne.
             const allOn = all.every((item) => list.includes(item));
             setCurrent(allOn ? list.filter((item) => !all.includes(item)) : [...list, ...all.filter((item) => !list.includes(item))]);
@@ -119,8 +139,8 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
                                     return;
                                 event.preventDefault();
                                 listRef.current?.focus();
-                            } })] })) : null, _jsx("div", { ref: listRef, className: "kpt-listbox__items", role: "listbox", id: field.id, tabIndex: disabled ? -1 : 0, "aria-multiselectable": multiple || undefined, "aria-activedescendant": activeOptionId, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, "aria-required": required || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onKeyDown: onKeyDown, onFocus: onFocus, onBlur: () => onTouch?.(), children: visible.length ? (visible.map((option, index) => (_jsxs("div", { role: "option", id: optionId(index), className: cn('kpt-listbox__item', isSelected(option.value) && 'is-selected', index === activeIndex && 'is-active'), "aria-selected": isSelected(option.value), "aria-disabled": disabledMap[index] || undefined, onMouseDown: (event) => {
+                            } })] })) : null, _jsx("div", { ref: listRef, className: "kpt-listbox__items", role: "listbox", id: field.id, tabIndex: disabled ? -1 : 0, "aria-multiselectable": multiple || undefined, "aria-activedescendant": activeOptionId, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, "aria-required": required || undefined, "aria-readonly": readOnly || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onKeyDown: onKeyDown, onFocus: onFocus, onBlur: () => onTouch?.(), children: visible.map((option, index) => (_jsxs("div", { role: "option", id: optionId(index), className: cn('kpt-listbox__item', isSelected(option.value) && 'is-selected', index === activeIndex && 'is-active'), "aria-selected": isSelected(option.value), "aria-disabled": disabledMap[index] || undefined, onMouseDown: (event) => {
                             event.preventDefault();
                             listRef.current?.focus();
-                        }, onClick: () => pick(index), children: [_jsx("span", { children: option.label }), isSelected(option.value) ? _jsx(KptIcon, { name: "check" }) : null] }, String(option.value))))) : (_jsx("div", { className: "kpt-listbox__empty", role: "status", children: t('listbox.empty') })) })] }) }));
+                        }, onClick: (event) => pick(index, event.shiftKey), children: [_jsx("span", { children: option.label }), isSelected(option.value) ? _jsx(KptIcon, { name: "check" }) : null] }, typeof option.value === 'object' && option.value !== null ? `#${index}` : String(option.value)))) }), visible.length === 0 ? (_jsx("div", { className: "kpt-listbox__empty", role: "status", children: t('listbox.empty') })) : null] }) }));
 }

package/dist/listbox/llms.txt

@@ -53,3 +53,6 @@ label (unless `ariaLabel` is set) and the hint or error in `aria-describedby`. N
 The list is `role="listbox"` with `aria-multiselectable`, `aria-activedescendant` and a name from
 `ariaLabel` or `KptFormField`; options are `role="option"` with `aria-selected`/`aria-disabled`.
 The keyboard is described above.
+
+## Read-only and required
+`readOnly` lets you move through the list and read the choice but not change it (`aria-readonly`). With `multiple`, `Shift+↑/↓` selects the option focus moves to and `Shift+click` adds the range from the last clicked option (APG). The empty message sits next to the list.

package/dist/map/llms.txt

@@ -41,7 +41,11 @@ a readable message.
 
 ## Events
 `onLocationClick`, `onClusterClick`, `onLocationCreate`, `onSearchSelect`, `onViewChange`,
-`onUserPositionChange`, `onUserLocationError`.
+`onUserPositionChange`, `onUserLocationError`, `onEngineError`.
+
+`onEngineError(error)` fires when the engine fails to start (no `leaflet` package, a rejected Google key);
+the error is also logged to the console. `followUser` and the position callbacks are read fresh on every
+fix, so changing them does not restart the geolocation watch.
 
 `onLocationCreate` gives `{ at, categoryId, value }` — the component appends **nothing** to
 `locations`; the application is the source of truth.

package/dist/map/map-create-dialog.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { emptyWeek, parseTime, weekdayName } from '@konce-pt/map';
 import { useEffect, useMemo, useState } from 'react';
@@ -40,6 +41,10 @@ function initialModel(fields) {
         out[def.key] = initialValue(def);
     return out;
 }
+/** Wartość pola tekstowego z modelu `unknown` — liczba zostaje liczbą zapisaną tekstem, reszta pustym napisem. */
+function asText(value) {
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : '';
+}
 /**
  * Treść dialogu „dodaj lokalizację" budowana ze schemy kategorii (`category.fields`).
  *
@@ -55,42 +60,48 @@ export function KptMapCreateDialog({ category, at, geocoder = null, onSave, onCa
     const [touched, setTouched] = useState({});
     /** Po nieudanej próbie zapisu pokazujemy błędy wszystkich pól, nie tylko dotkniętych. */
     const [submitted, setSubmitted] = useState(false);
-    /** Trwa zapytanie do geokodera — pokazujemy notkę zamiast ciszy. */
-    const [geocoding, setGeocoding] = useState(false);
     /** Ostatnio ustalony adres; `address` bywa czytelniejszy niż suma pól. */
     const [address, setAddress] = useState(null);
-    // Inna kategoria to inny formularz — model wraca do wartości początkowych.
-    const schemaRef = useMemo(() => fields, [fields]);
-    useEffect(() => {
-        setModel(initialModel(schemaRef));
+    // Inna kategoria to inny formularz — model wraca do wartości początkowych. Liczone w renderze
+    // (wzorzec poprzedniej wartości): efekt pokazałby jedną klatkę pól starej kategorii.
+    const [modelFields, setModelFields] = useState(fields);
+    if (modelFields !== fields) {
+        setModelFields(fields);
+        setModel(initialModel(fields));
         setTouched({});
         setSubmitted(false);
-    }, [schemaRef]);
+    }
     /** Czy kategoria ma pola do podpowiedzenia i jest czym je podpowiedzieć. */
     const autofillFields = useMemo(() => fields.filter((def) => def.autofill && TEXTUAL.has(def.type)), [fields]);
     const hasAutofill = !!geocoder && autofillFields.length > 0;
+    /** Tożsamość bieżącego zapytania do geokodera — nowa przy każdej zmianie jego wejść. */
+    const geocodeRequest = useMemo(() => (geocoder && autofillFields.length > 0 ? { geocoder, at, locale, autofillFields } : null), [geocoder, at, locale, autofillFields]);
+    /** Zapytanie, na które przyszła już odpowiedź (albo błąd). */
+    const [settledRequest, setSettledRequest] = useState(null);
+    /** Trwa zapytanie do geokodera — pokazujemy notkę zamiast ciszy. */
+    const geocoding = geocodeRequest !== null && settledRequest !== geocodeRequest;
     /**
      * Podpowiada adres z geokodowania wstecznego współrzędnych kliknięcia. Wypełnia wyłącznie
      * pola z `autofill` i wyłącznie te, które są jeszcze puste — podpowiedź nigdy nie kasuje
      * tego, co użytkownik zdążył wpisać.
      */
     useEffect(() => {
-        if (!geocoder || autofillFields.length === 0)
+        if (!geocodeRequest)
             return;
+        const request = geocodeRequest;
         const controller = new AbortController();
-        setGeocoding(true);
-        geocoder
-            .reverse(at, { language: locale, signal: controller.signal })
+        request.geocoder
+            .reverse(request.at, { language: request.locale, signal: controller.signal })
             .then((found) => {
             if (controller.signal.aborted)
                 return;
-            setGeocoding(false);
+            setSettledRequest(request);
             setAddress(found);
             if (!found)
                 return;
             setModel((current) => {
                 const next = { ...current };
-                for (const def of autofillFields) {
+                for (const def of request.autofillFields) {
                     const value = found[def.autofill];
                     // Puste pole = to, czego użytkownik nie tknął.
                     if (typeof value === 'string' && value && !next[def.key])
@@ -101,13 +112,10 @@ export function KptMapCreateDialog({ category, at, geocoder = null, onSave, onCa
         })
             .catch(() => {
             if (!controller.signal.aborted)
-                setGeocoding(false);
+                setSettledRequest(request);
         });
-        return () => {
-            controller.abort();
-            setGeocoding(false);
-        };
-    }, [geocoder, at, locale, autofillFields]);
+        return () => controller.abort();
+    }, [geocodeRequest]);
     /**
      * Komunikat błędu pola albo `null`. Dzień otwarty musi mieć obie godziny i różne od siebie;
      * dzień oznaczony jako zamknięty przechodzi bez zastrzeżeń — to prawidłowa odpowiedź,
@@ -174,7 +182,7 @@ export function KptMapCreateDialog({ category, at, geocoder = null, onSave, onCa
         const common = { onTouch: touch(def.key), invalid: !!visibleError(def), touched: !!touched[def.key] };
         switch (def.type) {
             case 'textarea':
-                return (_jsx(KptTextarea, { value: String(value ?? ''), onValueChange: (next) => set(def.key, next), placeholder: def.placeholder ?? '', ...common }));
+                return (_jsx(KptTextarea, { value: asText(value), onValueChange: (next) => set(def.key, next), placeholder: def.placeholder ?? '', ...common }));
             case 'number':
                 return (_jsx(KptInputNumber, { value: value, onValueChange: (next) => set(def.key, next), min: typeof def.min === 'number' ? def.min : undefined, max: typeof def.max === 'number' ? def.max : undefined, placeholder: def.placeholder ?? '', ...common }));
             case 'date':
@@ -186,11 +194,11 @@ export function KptMapCreateDialog({ category, at, geocoder = null, onSave, onCa
             case 'checkbox':
                 return (_jsx(KptCheckbox, { checked: !!value, onCheckedChange: (next) => set(def.key, next), label: def.placeholder ?? '', onTouch: touch(def.key) }));
             case 'image':
-                return (_jsx(KptMapImageField, { value: String(value ?? ''), onValueChange: (next) => set(def.key, next), invalid: !!visibleError(def), touched: !!touched[def.key], onTouch: touch(def.key) }));
+                return (_jsx(KptMapImageField, { value: asText(value), onValueChange: (next) => set(def.key, next), invalid: !!visibleError(def), touched: !!touched[def.key], onTouch: touch(def.key) }));
             case 'hours':
                 return (_jsx(KptMapHoursField, { value: value ?? emptyWeek(), onValueChange: (next) => set(def.key, next), onTouch: touch(def.key) }));
             default:
-                return (_jsx(KptInput, { id: controlId(def), type: def.type === 'tel' || def.type === 'email' || def.type === 'url' ? def.type : 'text', value: String(value ?? ''), onValueChange: (next) => set(def.key, next), placeholder: def.placeholder ?? (def.type === 'url' ? 'https://' : ''), ...common }));
+                return (_jsx(KptInput, { id: controlId(def), type: def.type === 'tel' || def.type === 'email' || def.type === 'url' ? def.type : 'text', value: asText(value), onValueChange: (next) => set(def.key, next), placeholder: def.placeholder ?? (def.type === 'url' ? 'https://' : ''), ...common }));
         }
     }
 }

package/dist/map/map-hours-field.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { emptyWeek, weekdayName } from '@konce-pt/map';
 import { useState } from 'react';

package/dist/map/map-image-field.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { cn } from "../internal/cn.js";
@@ -42,7 +43,7 @@ export function KptMapImageField({ value, onValueChange, disabled = false, readO
             return;
         }
         const reader = new FileReader();
-        reader.onload = () => onValueChange(String(reader.result ?? ''));
+        reader.onload = () => onValueChange((typeof reader.result === 'string' ? reader.result : ''));
         reader.onerror = () => setSizeError(t('map.field.imageTooLarge', { max: maxLabel }));
         reader.readAsDataURL(file);
     };

package/dist/map/map-legend.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { colorVarOf, contrastVarOf } from '@konce-pt/map';
 import { cn } from "../internal/cn.js";

package/dist/map/map-poi-card.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { foregroundVarOf, formatDistance, formatLatLng, groupWeek, isAlwaysOpen, isOpenAt, nextChange, normalizeUrl, prettyUrl, } from '@konce-pt/map';
 import { useId, useRef, useState } from 'react';
@@ -148,5 +149,5 @@ export function KptMapPoiCard({ poi, distance = null, category = null, primaryLa
                                     // Odświeżamy zegar przy rozwinięciu — karta bywa otwarta dłużej niż minutę.
                                     setNow(Date.now());
                                     setExpanded(!expanded);
-                                }, children: [_jsx(KptIcon, { className: "kpt-map-poi__row-icon", name: "clock" }), _jsx("span", { className: "kpt-map-poi__status", "data-open": open || alwaysOpen, children: statusLabel }), statusHint ? _jsxs("span", { className: "kpt-map-poi__status-hint", children: ["\u00B7 ", statusHint] }) : null, _jsx(KptIcon, { className: "kpt-map-poi__chevron", name: "chevron-down" })] }), expanded ? (_jsx("dl", { className: "kpt-map-poi__week", id: hoursId, children: hoursGroups.map((group) => (_jsxs("div", { style: { display: 'contents' }, children: [_jsx("dt", { className: "kpt-map-poi__week-day", children: group.label }), _jsx("dd", { className: "kpt-map-poi__week-hours", children: group.closed ? (_jsx("span", { className: "kpt-map-poi__week-closed", children: t('map.poi.closedDay') })) : (group.ranges.map((range) => (_jsx("span", { className: "kpt-map-poi__week-range", children: range }, range)))) })] }, group.label))) })) : null] })) : null, rows.length || poi.facts?.length ? (_jsxs("ul", { className: "kpt-map-poi__rows", children: [rows.map((row) => (_jsxs("li", { className: "kpt-map-poi__row", children: [_jsx(KptIcon, { className: "kpt-map-poi__row-icon", name: row.icon }), row.href ? (_jsx("a", { className: "kpt-map-poi__row-value kpt-map-poi__row-link", href: row.href, target: row.external ? '_blank' : undefined, rel: row.external ? 'noopener' : undefined, children: row.text })) : (_jsx("span", { className: "kpt-map-poi__row-value", children: row.text })), _jsxs("span", { className: "kpt-map-poi__row-actions", children: [row.href ? (_jsx("a", { className: "kpt-map-poi__row-action", href: row.href, target: row.external ? '_blank' : undefined, rel: row.external ? 'noopener' : undefined, "aria-label": row.actionLabel, title: row.actionLabel, children: _jsx(KptIcon, { name: row.actionIcon }) })) : null, canCopy ? (_jsx("button", { className: "kpt-map-poi__row-action", type: "button", "aria-label": t('map.poi.copy'), title: t('map.poi.copy'), onClick: () => void copy(row), children: _jsx(KptIcon, { name: justCopied === row.kind ? 'check' : 'copy' }) })) : null] })] }, row.kind))), (poi.facts ?? []).map((fact) => (_jsxs("li", { className: "kpt-map-poi__row kpt-map-poi__row--fact", children: [fact.icon ? (_jsx(KptIcon, { className: "kpt-map-poi__row-icon", name: fact.icon })) : (_jsx("span", { className: "kpt-map-poi__row-icon", "aria-hidden": "true" })), _jsxs("span", { className: "kpt-map-poi__row-value", children: [_jsx("span", { className: "kpt-map-poi__fact-label", children: fact.label }), " ", fact.value] })] }, fact.label)))] })) : null, _jsx("p", { className: "kpt-map-poi__live", "aria-live": "polite", children: justCopied ? t('map.poi.copied') : '' })] })] }));
+                                }, children: [_jsx(KptIcon, { className: "kpt-map-poi__row-icon", name: "clock" }), _jsx("span", { className: "kpt-map-poi__status", "data-open": open || alwaysOpen, children: statusLabel }), statusHint ? _jsxs("span", { className: "kpt-map-poi__status-hint", children: ["\u00B7 ", statusHint] }) : null, _jsx(KptIcon, { className: "kpt-map-poi__chevron", name: "chevron-down" })] }), expanded ? (_jsx("dl", { className: "kpt-map-poi__week", id: hoursId, children: hoursGroups.map((group) => (_jsxs("div", { style: { display: 'contents' }, children: [_jsx("dt", { className: "kpt-map-poi__week-day", children: group.label }), _jsx("dd", { className: "kpt-map-poi__week-hours", children: group.closed ? (_jsx("span", { className: "kpt-map-poi__week-closed", children: t('map.poi.closedDay') })) : (group.ranges.map((range) => (_jsx("span", { className: "kpt-map-poi__week-range", children: range }, range)))) })] }, group.label))) })) : null] })) : null, rows.length || poi.facts?.length ? (_jsxs("ul", { className: "kpt-map-poi__rows", children: [rows.map((row) => (_jsxs("li", { className: "kpt-map-poi__row", children: [_jsx(KptIcon, { className: "kpt-map-poi__row-icon", name: row.icon }), row.href ? (_jsx("a", { className: "kpt-map-poi__row-value kpt-map-poi__row-link", href: row.href, target: row.external ? '_blank' : undefined, rel: row.external ? 'noopener noreferrer' : undefined, children: row.text })) : (_jsx("span", { className: "kpt-map-poi__row-value", children: row.text })), _jsxs("span", { className: "kpt-map-poi__row-actions", children: [row.href ? (_jsx("a", { className: "kpt-map-poi__row-action", href: row.href, target: row.external ? '_blank' : undefined, rel: row.external ? 'noopener noreferrer' : undefined, "aria-label": row.actionLabel, title: row.actionLabel, children: _jsx(KptIcon, { name: row.actionIcon }) })) : null, canCopy ? (_jsx("button", { className: "kpt-map-poi__row-action", type: "button", "aria-label": t('map.poi.copy'), title: t('map.poi.copy'), onClick: () => void copy(row), children: _jsx(KptIcon, { name: justCopied === row.kind ? 'check' : 'copy' }) })) : null] })] }, row.kind))), (poi.facts ?? []).map((fact) => (_jsxs("li", { className: "kpt-map-poi__row kpt-map-poi__row--fact", children: [fact.icon ? (_jsx(KptIcon, { className: "kpt-map-poi__row-icon", name: fact.icon })) : (_jsx("span", { className: "kpt-map-poi__row-icon", "aria-hidden": "true" })), _jsxs("span", { className: "kpt-map-poi__row-value", children: [_jsx("span", { className: "kpt-map-poi__fact-label", children: fact.label }), " ", fact.value] })] }, fact.label)))] })) : null, _jsx("p", { className: "kpt-map-poi__live", "aria-live": "polite", children: justCopied ? t('map.poi.copied') : '' })] })] }));
 }