@konce-pt/react 0.11.2 → 0.14.0

package/dist/knob/knob.js

@@ -1,37 +1,42 @@
+'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";
 const TAU = Math.PI * 2;
-/** Przerwa u dołu — kąt „otwarcia" łuku, żeby początek i koniec były rozróżnialne. */
+/** Przerwa u dołu - kąt "otwarcia" łuku, żeby początek i koniec były rozróżnialne. */
 const GAP = Math.PI / 4;
 const START_ANGLE = Math.PI / 2 + GAP;
 const SWEEP = TAU - GAP * 2;
 /** Czas dojścia łuku i licznika po skoku wartości (klawisz, klik, zmiana z zewnątrz). */
 const TWEEN_MS = 220;
 /**
- * Pokrętło — wybór wartości po łuku, przeciąganiem albo strzałkami.
+ * 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 });
     const showInvalid = invalid && (touched ?? true);
     const range = max - min;
-    /** Wartość na rysunku — w trakcie animacji pośrednia, poza nią równa `current`. */
+    /** Wartość na rysunku - w trakcie animacji pośrednia, poza nią równa `current`. */
     const [shown, setShown] = useState(current);
     const shownRef = useRef(current);
-    /** Przeciąganie trwa — wtedy rysunek idzie za kursorem bez animacji. */
+    /** Przeciąganie trwa - wtedy rysunek idzie za kursorem bez animacji. */
     const dragging = useRef(false);
+    /** Pokrętło trzymane wskaźnikiem (od wciśnięcia do puszczenia) - steruje reakcją w CSS. */
+    const [grabbing, setGrabbing] = useState(false);
     useEffect(() => {
         const paint = (v) => {
             shownRef.current = v;
@@ -58,7 +63,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)
@@ -68,23 +72,24 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
         const cy = rect.top + rect.height / 2;
         let angle = Math.atan2(clientY - cy, clientX - cx) - START_ANGLE;
         angle = ((angle % TAU) + TAU) % TAU;
-        // Kursor w przerwie u dołu nie ma swojej wartości — przyciągamy go do bliższego końca łuku,
+        // Kursor w przerwie u dołu nie ma swojej wartości - przyciągamy go do bliższego końca łuku,
         // 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
+        // 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.
         event.preventDefault();
         event.currentTarget.focus();
-        // Klik w łuk to skok — animowany. Dopiero ruch po nim jest przeciąganiem.
+        setGrabbing(true);
+        // Klik w łuk to skok - animowany. Dopiero ruch po nim jest przeciąganiem.
         setFromPoint(event.clientX, event.clientY);
         // Nasłuch wisi na oknie, a nie na pokrętle: przeciąganie ma nie gubić wartości,
-        // gdy kursor wyjedzie poza koło — a wyjeżdża praktycznie zawsze.
+        // gdy kursor wyjedzie poza koło - a wyjeżdża praktycznie zawsze.
         const move = (e) => {
             dragging.current = true;
             setFromPoint(e.clientX, e.clientY);
@@ -94,6 +99,7 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
             window.removeEventListener('pointerup', up);
             window.removeEventListener('pointercancel', up);
             dragging.current = false;
+            setGrabbing(false);
             onTouch?.();
         };
         window.addEventListener('pointermove', move);
@@ -101,22 +107,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', grabbing && 'is-grabbing'), 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

@@ -1,36 +1,37 @@
 # KptKnob (@konce-pt/react)
 
-A knob — pick a value along an SVG arc, by dragging or with the arrow keys.
+A knob - pick a value along an SVG arc, by dragging or with the arrow keys.
 Import: `import { KptKnob } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-knob-host">
       <div class="kpt-knob" role="slider" tabindex="0" aria-valuenow="40">
         <svg viewBox="0 0 96 96">
-          <path class="kpt-knob__range" d="M …" />
-          <path class="kpt-knob__value" d="M …" />
+          <path class="kpt-knob__range" d="M ..." />
+          <path class="kpt-knob__value" d="M ..." />
           <text class="kpt-knob__text">40%</text>
         </svg>
       </div>
     </div>
 
 ## Props
-- `value` / `defaultValue` / `onValueChange` — the number
+- `value` / `defaultValue` / `onValueChange` - the number
 - `min` (0), `max` (100), `step` (1)
-- `size`: px (96) — the side of the SVG square; `stroke`: px (10) — arc thickness
+- `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
 The arc is a full circle minus a 45° gap at the bottom, so its start and end are distinguishable.
-A pointer inside that gap has no value of its own — it is snapped to the nearer end, otherwise
+A pointer inside that gap has no value of its own - it is snapped to the nearer end, otherwise
 dragging across the bottom would jump between minimum and maximum.
 
 ## Dragging listens on the window
 `pointermove` / `pointerup` are attached to `window`, not to the knob: the pointer leaves the
 circle during almost every drag, and the value must keep following it. Both listeners are removed
-on `pointerup`, which is also where `onTouch` fires — one touch per drag, not per pixel.
+on `pointerup`, which is also where `onTouch` fires - one touch per drag, not per pixel.
 
 ## Examples
     <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
@@ -41,15 +42,20 @@ on `pointerup`, which is also where `onTouch` fires — one touch per drag, not
 generated. A `div` with a role is not named by `label[for]`, so inside `KptFormField` it gets
 `aria-labelledby` pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error
 is added to `aria-describedby`. New: `id`, `ariaLabel`; `aria-valuetext` includes `suffix` ("40%"),
-and a disabled knob leaves the Tab order. Use `ariaLabel`, not `aria-label` on the host — that one
+and a disabled knob leaves the Tab order. Use `ariaLabel`, not `aria-label` on the host - that one
 lands on the wrapper.
 
+## Pointer
+While held (from press to release) the knob reacts: the cursor becomes `grabbing`, the dial grows
+slightly, the value arc glows stronger and the number in the middle scales up. On hover the arc glows
+softly. All of it is CSS on the `is-grabbing` class and drops out under "reduce motion".
+
 ## Tokens
 The background arc `--kpt-color-border`, the value `--kpt-color-primary`, the text
 `--kpt-color-on-surface`.
 
 ## Motion
-A jump in value — an arrow key, Home/End, a click on the arc, a change from outside — moves the arc
+A jump in value - an arrow key, Home/End, a click on the arc, a change from outside - moves the arc
 and counts the number up or down over ~220 ms (ease-out). Dragging follows the pointer with no
 delay, so it never feels laggy. `prefers-reduced-motion: reduce` turns the animation off.
 `aria-valuenow` always carries the target value, never an in-between frame. Dragging does not
@@ -57,5 +63,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

@@ -9,13 +9,15 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
     multiple?: boolean;
     /** Pole filtrowania nad listą. */
     filter?: boolean;
-    /** Id listy (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    /** Id listy (nie hosta); bez niego generowane, w `KptFormField` - z wrappera. */
     id?: string;
     /** Nazwa dostępna listy, gdy nie opisuje jej etykieta (`KptFormField`). */
     ariaLabel?: string | null;
     /** 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;
@@ -24,17 +26,17 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
  * Lista wyboru widoczna w całości, bez rozwijania. Pojedynczy albo wielokrotny wybór,
  * opcjonalny filtr.
  *
- * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją — lista bywa filtrem,
+ * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją - lista bywa filtrem,
  * a filtr trzeba dać się wyczyścić bez sięgania po osobny przycisk.
  *
- * Klawiatura według wzorca WAI-ARIA „listbox”: lista to jeden przystanek Tab, a aktywną opcję
+ * Klawiatura według wzorca WAI-ARIA "listbox": lista to jeden przystanek Tab, a aktywną opcję
  * ogłasza `aria-activedescendant`. Strzałki, `Home`/`End`, `PageUp`/`PageDown` przesuwają aktywną
  * opcję (wyłączone są pomijane), pisanie liter skacze do kolejnej pasującej (bez względu na
- * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`⌘`+`A` zaznacza wszystkie
- * widoczne. Pole filtra stoi przed listą; `↓` przenosi z niego fokus do listy.
+ * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`Cmd`+`A` zaznacza wszystkie
+ * widoczne. Pole filtra stoi przed listą; `ArrowDown` przenosi z niego fokus do listy.
  *
  * @example
  * <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';
@@ -11,22 +12,22 @@ import { KptIcon } from "../icon/icon.js";
  * Lista wyboru widoczna w całości, bez rozwijania. Pojedynczy albo wielokrotny wybór,
  * opcjonalny filtr.
  *
- * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją — lista bywa filtrem,
+ * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją - lista bywa filtrem,
  * a filtr trzeba dać się wyczyścić bez sięgania po osobny przycisk.
  *
- * Klawiatura według wzorca WAI-ARIA „listbox”: lista to jeden przystanek Tab, a aktywną opcję
+ * Klawiatura według wzorca WAI-ARIA "listbox": lista to jeden przystanek Tab, a aktywną opcję
  * ogłasza `aria-activedescendant`. Strzałki, `Home`/`End`, `PageUp`/`PageDown` przesuwają aktywną
  * opcję (wyłączone są pomijane), pisanie liter skacze do kolejnej pasującej (bez względu na
- * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`⌘`+`A` zaznacza wszystkie
- * widoczne. Pole filtra stoi przed listą; `↓` przenosi z niego fokus do listy.
+ * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`Cmd`+`A` zaznacza wszystkie
+ * widoczne. Pole filtra stoi przed listą; `ArrowDown` przenosi z niego fokus do listy.
  *
  * @example
  * <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. */
+    /** `div` z rolą nie dostaje nazwy z `label[for]` - stąd `aria-labelledby` na etykietę wrappera. */
     const field = useKptFieldA11y(id, 'kpt-listbox');
     const [current, setCurrent] = useControllableState({
         value,
@@ -39,7 +40,7 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
     const listRef = useRef(null);
     const typeahead = useRef(new KptTypeahead()).current;
     const showInvalid = invalid && (touched ?? true);
-    /** Filtr bez względu na wielkość liter i diakrytyki („lodz” znajduje „Łódź”). */
+    /** Filtr bez względu na wielkość liter i diakrytyki ("lodz" znajduje "Łódź"). */
     const visible = useMemo(() => {
         const q = foldMentionText(query.trim());
         return q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
@@ -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,11 +119,11 @@ 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 : [];
-            // Drugi raz `Ctrl+A` przy wszystkich zaznaczonych — odznacza widoczne.
+            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))]);
             return;
@@ -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

@@ -6,19 +6,19 @@ Import: `import { KptListbox } from '@konce-pt/react';`
 ## DOM
     <div class="kpt-listbox-host">
       <div class="kpt-listbox">
-        <div class="kpt-listbox__filter">…icon + input…</div>
-        <div class="kpt-listbox__items" role="listbox" tabindex="0" aria-activedescendant="…-opt-0">
-          <div class="kpt-listbox__item is-selected is-active" role="option" id="…-opt-0" aria-selected="true">Admin</div>
+        <div class="kpt-listbox__filter">...icon + input...</div>
+        <div class="kpt-listbox__items" role="listbox" tabindex="0" aria-activedescendant="...-opt-0">
+          <div class="kpt-listbox__item is-selected is-active" role="option" id="...-opt-0" aria-selected="true">Admin</div>
         </div>
       </div>
     </div>
 
 ## Props
 - `options`: `KptOption<T>[]`
-- `value` / `defaultValue` / `onValueChange` — `T` (single) or `T[]` (multiple)
+- `value` / `defaultValue` / `onValueChange` - `T` (single) or `T[]` (multiple)
 - `multiple`, `filter`, `disabled`, `invalid`, `touched`, `onTouch()`
 - `id`, `ariaLabel`, `required`
-- `locale`, `dictionary` — i18n overrides for this component only
+- `locale`, `dictionary` - i18n overrides for this component only
 
 ## Clicking the selection clears it
 In single mode clicking the already selected option deselects it. A listbox is often a filter, and a
@@ -33,17 +33,17 @@ filter has to be clearable without a separate button.
 
 ## Keyboard
 The WAI-ARIA listbox pattern: the list is one Tab stop and the active option is announced through
-`aria-activedescendant`. `↑`/`↓`, `Home`/`End` and `PageUp`/`PageDown` move the active option,
+`aria-activedescendant`. `ArrowUp`/`ArrowDown`, `Home`/`End` and `PageUp`/`PageDown` move the active option,
 skipping disabled ones (no wrapping); typing letters jumps to the next match, diacritics ignored;
-`Space`/`Enter` picks; in `multiple` mode `Ctrl`/`⌘`+`A` selects every visible option (again —
-clears them). The filter field sits before the list (outside the `listbox`) and `↓` moves focus
+`Space`/`Enter` picks; in `multiple` mode `Ctrl`/`Cmd`+`A` selects every visible option (again -
+clears them). The filter field sits before the list (outside the `listbox`) and `ArrowDown` moves focus
 from it into the list; the filter itself ignores diacritics ("lodz" finds "Łódź").
 
 ## Label and description
 `id` goes to the list (`role="listbox"`), never the host. A `div` with a role is not named by
 `label[for]`, so inside `KptFormField` the list gets `aria-labelledby` pointing at the wrapper's
 label (unless `ariaLabel` is set) and the hint or error in `aria-describedby`. New: `id`,
-`ariaLabel`, `required` (→ `aria-required`); `aria-invalid` after touch; `touch` fires on blur of the list.
+`ariaLabel`, `required` (-> `aria-required`); `aria-invalid` after touch; `touch` fires on blur of the list.
 
 ## Tokens
 `--kpt-color-surface`, `--kpt-color-border`, `--kpt-color-primary-subtle` (the selected row),
@@ -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+ArrowUp/ArrowDown` 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/loader/llms.txt

@@ -0,0 +1,56 @@
+# KptLoader (@konce-pt/react)
+
+A loader with character: a loop in one of six materials that turns into a result mark instead of
+disappearing. Same classes and the same drawing as `kpt-loader` in Angular - the SVG and its
+choreography come from `createLoader` in `@konce-pt/motion`. Import:
+`import { KptLoader } from '@konce-pt/react';`
+
+Variants: `bubbles` (default), `bridge` (the result is a pill with text), `shapes`, `ring` (progress,
+an icon in the centre), `wave` (progress), `bounce`. Use `KptSpinner` for a small inline "wait".
+
+## DOM
+    <span class="kpt-loader-host">
+      <span class="kpt-loader" data-variant="bubbles" data-status="loading" style="--_size: 5rem">
+        <span class="kpt-loader__stage" aria-hidden="true"><svg class="kpt-loader__svg">...</svg></span>
+        <span class="kpt-loader__content"></span>
+        <span class="kpt-loader__label" role="status">Loading</span>
+      </span>
+    </span>
+
+## Props
+- `variant`: KptLoaderVariant (default 'bubbles')
+- `status`: 'loading' | 'success' | 'error' (default 'loading') - a result plays once and the mark
+  stays; back to `loading` restarts the loop
+- `value`: number | null (default null), `min` (0), `max` (100) - progress for `ring` and `wave`
+- `size`: string (default '5rem') - the CSS length of 100 drawing units, shared by all variants
+- `colors`: KptLoaderColor[] | null - theme roles ('primary', 'info', 'success', 'warning',
+  'danger') or CSS colours, repeated in order; without it each variant has its palette
+- `successColor` (default 'success'), `errorColor` (default 'danger')
+- `speed`: number (default 1) - multiplies the loop tempo
+- `label`, `successLabel`, `errorLabel`: string - default `loader.label`, `loader.success`,
+  `loader.error`; the result texts also go into the `bridge` pill and follow the language live
+- `announce`: boolean (default true) - `false` drops the own status region
+- `onSettled`: (result: KptLoaderResult) => void - the result choreography has finished; not called
+  when the loader mounts already in a result
+- `children` - content in the centre of `ring` (other variants ignore it)
+- `locale`, `dictionary` - i18n overrides for this component only
+- `className`, `style`, `ref` and other `<span>` props go to `.kpt-loader`; `hostProps` to the wrapper
+
+## Examples
+    <KptLoader />
+    <KptLoader variant="bridge" status={saving ? 'loading' : 'success'} onSettled={() => setShown(false)} />
+    <KptLoader variant="wave" value={uploaded} max={total} />
+    <KptLoader variant="ring" status={status}><KptIcon name="download" /></KptLoader>
+    <KptLoader variant="bounce" colors={['danger', 'oklch(0.6 0.2 300)']} speed={1.5} />
+
+## Tokens
+Roles resolve to `--kpt-color-<role>`, marks on filled shapes to `--kpt-color-<role>-contrast`
+(a custom colour gets `--kpt-color-surface`), the `shapes` backdrop to `--kpt-color-<role>-subtle`;
+tracks `--kpt-color-border`, shadows `--kpt-color-overlay-scrim`.
+
+## Motion and accessibility
+One `requestAnimationFrame` loop per loader, stopped off-screen and after the result.
+`<KptMotionProvider enabled={false}>` and the system "reduce motion" setting slow the loop down and
+replace the choreography with the mark in a circle. The drawing is `aria-hidden`; a visually hidden
+`role="status"` region gets the label a frame after mount, then the result text. While `ring` or
+`wave` draws progress the stage is a `role="progressbar"` with `aria-valuenow` 0-100.

package/dist/loader/loader.d.ts

@@ -0,0 +1,49 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type KptLoaderColor, type KptLoaderResult, type KptLoaderStatus, type KptLoaderVariant } from '@konce-pt/motion';
+import type { KptHostProps } from '../internal/types.ts';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+export type { KptLoaderColor, KptLoaderResult, KptLoaderStatus, KptLoaderVariant } from '@konce-pt/motion';
+export interface KptLoaderProps extends Omit<ComponentPropsWithRef<'span'>, 'children'>, KptI18nOverrides {
+    /** Materiał pętli. Domyślnie `bubbles`. */
+    variant?: KptLoaderVariant;
+    /** `loading` - pętla; `success` / `error` - choreografia wyniku i znak, który zostaje. */
+    status?: KptLoaderStatus;
+    /** Postęp (`ring`, `wave`); `null` = nieokreślony. Zakres jak w `KptProgress`. */
+    value?: number | null;
+    min?: number;
+    max?: number;
+    /** Długość 100 jednostek rysunku (CSS). Wszystkie warianty dzielą skalę. Domyślnie `5rem`. */
+    size?: string;
+    /** Barwy pętli - role motywu (`primary`, `info`, ...) albo kolory CSS; powtarzane po kolei. */
+    colors?: readonly KptLoaderColor[] | null;
+    successColor?: KptLoaderColor;
+    errorColor?: KptLoaderColor;
+    /** Mnożnik tempa pętli. Domyślnie 1. */
+    speed?: number;
+    /** Etykieta a11y w trakcie; pominięta = `loader.label`. */
+    label?: string;
+    /** Napis sukcesu (region statusu i kapsuła `bridge`); pominięty = `loader.success`. */
+    successLabel?: string;
+    /** Napis błędu; pominięty = `loader.error`. */
+    errorLabel?: string;
+    /** `false` - bez własnego regionu statusu (stan ogłasza komponent wokół, np. `KptUpdate`). */
+    announce?: boolean;
+    /** Koniec choreografii wyniku - dobry moment, żeby schować loader. */
+    onSettled?: (result: KptLoaderResult) => void;
+    /** Treść w środku pierścienia (`ring`) - np. ikona. */
+    children?: ReactNode;
+    /** Propsy wrappera `kpt-loader-host` (odpowiednik hosta Angulara). */
+    hostProps?: KptHostProps<'span'>;
+}
+/**
+ * Loader z charakterem: pętla w jednym z sześciu materiałów, która przy `status` `success` albo
+ * `error` przechodzi w znak wyniku zamiast znikać. Te same klasy co `kpt-loader` w Angularze,
+ * a rysunek i choreografię daje `createLoader` z `@konce-pt/motion` - wspólne dla obu portów.
+ *
+ * @example
+ * <KptLoader />
+ * <KptLoader variant="bridge" status={saving ? 'loading' : 'success'} />
+ * <KptLoader variant="wave" value={uploaded} max={total} />
+ * <KptLoader variant="ring" status={status}><KptIcon name="download" /></KptLoader>
+ */
+export declare function KptLoader({ variant, status, value, min, max, size, colors, successColor, errorColor, speed, label, successLabel, errorLabel, announce, onSettled, locale, dictionary, children, hostProps, className, style, ...rest }: Readonly<KptLoaderProps>): import("react").JSX.Element;

package/dist/loader/loader.js

@@ -0,0 +1,68 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useEffectEvent, useRef, useState } from 'react';
+import { createLoader, loaderProgress, } from '@konce-pt/motion';
+import { cn } from "../internal/cn.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
+import { useKptMotion } from "../motion/motion-context.js";
+/**
+ * Loader z charakterem: pętla w jednym z sześciu materiałów, która przy `status` `success` albo
+ * `error` przechodzi w znak wyniku zamiast znikać. Te same klasy co `kpt-loader` w Angularze,
+ * a rysunek i choreografię daje `createLoader` z `@konce-pt/motion` - wspólne dla obu portów.
+ *
+ * @example
+ * <KptLoader />
+ * <KptLoader variant="bridge" status={saving ? 'loading' : 'success'} />
+ * <KptLoader variant="wave" value={uploaded} max={total} />
+ * <KptLoader variant="ring" status={status}><KptIcon name="download" /></KptLoader>
+ */
+export function KptLoader({ variant = 'bubbles', status = 'loading', value = null, min = 0, max = 100, size = '5rem', colors = null, successColor = 'success', errorColor = 'danger', speed = 1, label, successLabel, errorLabel, announce = true, onSettled, locale, dictionary, children, hostProps, className, style, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
+    const motion = useKptMotion();
+    const stageRef = useRef(null);
+    const contentRef = useRef(null);
+    const controllerRef = useRef(null);
+    const [ready, setReady] = useState(false);
+    const effectiveLabel = label ?? t('loader.label');
+    const successText = successLabel ?? t('loader.success');
+    const errorText = errorLabel ?? t('loader.error');
+    const progress = loaderProgress(value, min, max);
+    // Postęp widać tylko w `ring` i `wave` - tylko tam loader jest paskiem postępu dla czytnika.
+    const determinate = status === 'loading' && progress !== null && (variant === 'ring' || variant === 'wave');
+    const reduced = motion?.enabled === false;
+    const settled = useEffectEvent((result) => onSettled?.(result));
+    // Najświeższe opcje dla efektów - bez przepisywania refa w trakcie renderu.
+    const currentOptions = useEffectEvent(() => ({
+        variant,
+        status,
+        progress,
+        colors,
+        successColor,
+        errorColor,
+        successText,
+        errorText,
+        speed,
+        reduced,
+        onSettled: (result) => settled(result),
+    }));
+    useEffect(() => {
+        if (!stageRef.current)
+            return;
+        const controller = createLoader(stageRef.current, contentRef.current, currentOptions());
+        controllerRef.current = controller;
+        // Tekst regionu statusu wpisujemy klatkę po pojawieniu się - pusty region nie jest ogłaszany.
+        const frame = requestAnimationFrame(() => setReady(true));
+        return () => {
+            cancelAnimationFrame(frame);
+            controller.destroy();
+            controllerRef.current = null;
+        };
+    }, []);
+    const colorsKey = (colors ?? []).join('|');
+    useEffect(() => {
+        controllerRef.current?.update(currentOptions());
+    }, [variant, status, progress, colorsKey, successColor, errorColor, successText, errorText, speed, reduced]);
+    const announced = !ready ? '' : status === 'success' ? successText : status === 'error' ? errorText : effectiveLabel;
+    const { className: hostClassName, ...hostRest } = hostProps ?? {};
+    return (_jsx("span", { className: cn('kpt-loader-host', hostClassName), ...hostRest, children: _jsxs("span", { className: cn('kpt-loader', className), "data-variant": variant, "data-status": status, style: { '--_size': size, ...style }, ...rest, children: [_jsx("span", { ref: stageRef, className: "kpt-loader__stage", role: determinate ? 'progressbar' : undefined, "aria-hidden": determinate ? undefined : true, "aria-label": determinate ? effectiveLabel : undefined, "aria-valuemin": determinate ? 0 : undefined, "aria-valuemax": determinate ? 100 : undefined, "aria-valuenow": determinate ? Math.round((progress ?? 0) * 100) : undefined }), _jsx("span", { ref: contentRef, className: "kpt-loader__content", children: children }), announce ? (_jsx("span", { className: "kpt-loader__label", role: "status", children: announced })) : null] }) }));
+}