@konce-pt/react 0.12.0 → 0.14.0

package/dist/knob/knob.d.ts

@@ -13,23 +13,23 @@ export interface KptKnobProps extends Omit<ComponentPropsWithRef<'div'>, 'onChan
     /** Dopisek za wartością w środku (np. '%'). */
     suffix?: string;
     showValue?: boolean;
-    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` - z wrappera. */
     id?: string;
     /** 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. */
+    /** 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;
 }
 /**
- * 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. `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
+ * 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

package/dist/knob/knob.js

@@ -7,18 +7,18 @@ 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. `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
+ * 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
@@ -30,11 +30,13 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
     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;
@@ -70,7 +72,7 @@ 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;
@@ -79,14 +81,15 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
     const onPointerDown = (event) => {
         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);
@@ -96,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);
@@ -119,5 +123,5 @@ export function KptKnob({ value, defaultValue = 0, onValueChange, min = 0, max =
         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-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] }) }) }));
+    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,37 +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`, `readOnly`, `invalid`, `touched`, `onTouch()` — `readOnly` keeps the knob focusable but ignores
+- `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="%" />
@@ -42,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
@@ -58,6 +63,6 @@ select the number or the arc.
 
 ## Accessibility
 `role="slider"` with `aria-valuemin` / `aria-valuemax` / `aria-valuenow`; arrows step by `step`,
-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
+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,14 +9,14 @@ 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ć. */
+    /** 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;
@@ -26,14 +26,14 @@ 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 />

package/dist/listbox/listbox.js

@@ -12,14 +12,14 @@ 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 />
@@ -27,7 +27,7 @@ import { KptIcon } from "../icon/icon.js";
  */
 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,
@@ -40,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;
@@ -63,7 +63,7 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
             setCurrent(current === candidate ? null : candidate);
         }
     };
-    /** Ostatnio kliknięta opcja — początek zakresu dla `Shift+klik` w trybie `multiple`. */
+    /** 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];
@@ -71,7 +71,7 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
             return;
         setActiveIndex(index);
         if (extend && multiple && anchorIndex.current >= 0) {
-            // Zaznacza (dokłada) dozwolone opcje między kotwicą a klikniętą — `Shift+klik` (APG).
+            // 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
@@ -123,7 +123,7 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
             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.
+            // 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;

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),
@@ -55,4 +55,4 @@ The list is `role="listbox"` with `aria-multiselectable`, `aria-activedescendant
 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.
+`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] }) }));
+}

package/dist/map/llms.txt

@@ -9,34 +9,37 @@ interface.
 Import: `import { KptMap, createLeafletEngine } from '@konce-pt/react/map';`
 
 ## Requirements
-1. The **optional** `leaflet` dependency — the library does not install it: `pnpm add leaflet`
+1. The **optional** `leaflet` dependency - the library does not install it: `pnpm add leaflet`
 2. Its stylesheet: `import 'leaflet/dist/leaflet.css';`
 3. An engine factory on the `engine` prop: `engine={() => createLeafletEngine()}`
 
 Leaflet is loaded with a dynamic `import()`, so an app that never renders a map does not download
-it. Without the package the component still imports and compiles — only rendering the map ends with
+it. Without the package the component still imports and compiles - only rendering the map ends with
 a readable message.
 
 ## Props
-- `locations`: `readonly KptMapLocation<T>[]` — **required**
-- `categories`: `readonly KptMapCategory[]` — **required**
-- `engine`: `KptMapEngineFactory` — **required**; a factory, not an instance, because every map
+- `locations`: `readonly KptMapLocation<T>[]` - **required**
+- `categories`: `readonly KptMapCategory[]` - **required**
+- `engine`: `KptMapEngineFactory` - **required**; a factory, not an instance, because every map
   needs its own object. Read once, at mount.
-- `country`: string = `'PL'` — the initial view preset; an unknown code falls back to Poland
-- `view`, `bounds` — an explicit view or extent; they override `country`
-- `restrictToCountry`: boolean — blocks panning outside the country's bounds
+- `country`: string = `'PL'` - the initial view preset; an unknown code falls back to Poland
+- `view`, `bounds` - an explicit view or extent; they override `country`
+- `restrictToCountry`: boolean - blocks panning outside the country's bounds
 - `cluster`: boolean = true, `clusterOptions`, `clusterColorBy`: `'dominant' | 'none'`
 - `legend`, `legendCounts`: boolean = true
-- `hiddenCategories` / `defaultHiddenCategories` / `onHiddenCategoriesChange` — the ids hidden in
+- `hiddenCategories` / `defaultHiddenCategories` / `onHiddenCategoriesChange` - the ids hidden in
   the legend, controlled or uncontrolled
 - `showUserLocation`, `followUser`: boolean; `geolocation`: `KptMapGeolocationPort | null`
-- `allowCreate`: boolean — the "Add location" menu under the right mouse button
+- `allowCreate`: boolean - the "Add location" menu under the right mouse button
 - `search`: boolean, `searchPlaceholder`, `searchOptions`, `searchZoom`, `searchMarker`
-- `geocoder`: `KptMapGeocoderPort | null` — this map's geocoder; it feeds both the search and the
+- `searchSpeech`: boolean = false - a microphone in the search field: a click clears the phrase and one
+  spoken utterance becomes the query (same `debounce`/`minLength` as typing); `searchSpeechLang`: string -
+  its language (BCP 47); `searchSpeechColor` - listening colour (theme colour by default). Hidden without browser support. `KptMapSearch` on its own takes `speech` / `speechLang` / `speechColor`
+- `geocoder`: `KptMapGeocoderPort | null` - this map's geocoder; it feeds both the search and the
   address suggestions in the create form
 - `popupLayout`: `'plain' | 'card'`; `distanceFrom`: `KptLatLng | null`
 - `height`: string = `'480px'`; `tileUrl`, `attribution` (ignored by the Google engine)
-- `renderPopup`, `renderCreateForm` — see below
+- `renderPopup`, `renderCreateForm` - see below
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Events
@@ -47,12 +50,12 @@ a readable message.
 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
+`onLocationCreate` gives `{ at, categoryId, value }` - the component appends **nothing** to
 `locations`; the application is the source of truth.
 
 ## Render props instead of templates
-The Angular port picks a popup template per category (`kptMapPopup category="…"`). React has one
-prop and a `switch`: `renderPopup({ location, data, category, distance, close })` — the category
+The Angular port picks a popup template per category (`kptMapPopup category="..."`). React has one
+prop and a `switch`: `renderPopup({ location, data, category, distance, close })` - the category
 travels in the context, and the type of `data` follows the map's generic without an extra input.
 
     <KptMap
@@ -68,7 +71,7 @@ travels in the context, and the type of `data` follows the map's generic without
 
 ## Ports are props, not DI
 Angular injects `KPT_MAP_ENGINE`, `KPT_MAP_GEOCODER` and `KPT_MAP_GEOLOCATION`. React has no
-injector, so all three arrive as props — and the geocoder was already per-map in Angular for a
+injector, so all three arrive as props - and the geocoder was already per-map in Angular for a
 licensing reason (a Google geocoder may only be paired with a Google map), so nothing is lost.
 
 The ports themselves are promise-shaped rather than `Observable`-shaped: `reverse()`, `search()`
@@ -76,7 +79,7 @@ and `resolve()` return promises and take an `AbortSignal`, which is what `fetch`
 
     import { createNominatimGeocoder, browserGeolocation } from '@konce-pt/react/map';
 
-    <KptMap geocoder={createNominatimGeocoder()} geolocation={browserGeolocation()} … />
+    <KptMap geocoder={createNominatimGeocoder()} geolocation={browserGeolocation()} ... />
 
 `createGeocoderStub()` and `geolocationStub(at)` cover demos and tests.
 
@@ -87,18 +90,18 @@ second mount waits for the first teardown to finish, instead of failing with "Ma
 already initialized".
 
 ## Sub-components
-- `KptMapLegend` — the legend on its own, when you want it somewhere other than under the map
+- `KptMapLegend` - the legend on its own, when you want it somewhere other than under the map
   (`hiddenCategories` instead of Angular's `hidden`: `hidden` on a DOM element is a boolean and
   would clash with the `<div>` prop)
-- `KptMapPoiCard` — the ready-made place card for `popupLayout="card"`
-- `KptMapSearch` — the address field alone
-- `KptMapCreateDialog`, `KptMapHoursField`, `KptMapImageField` — the schema-built form and its two
+- `KptMapPoiCard` - the ready-made place card for `popupLayout="card"`
+- `KptMapSearch` - the address field alone
+- `KptMapCreateDialog`, `KptMapHoursField`, `KptMapImageField` - the schema-built form and its two
   non-trivial field types
 
 ## Validation without a form framework
 The create dialog is built from `category.fields`. The Angular port stands on Signal Forms; here the
 model is plain state and the rules are a map of functions beside it. The contract is the same:
-declared once with the schema, and the "do not shout in red" gate lives in presentation — an error
+declared once with the schema, and the "do not shout in red" gate lives in presentation - an error
 shows after the field is touched or after a failed submit.
 
 ## Tokens