@konce-pt/react 0.11.2 → 0.14.0

package/dist/splitter/splitter.js

@@ -1,6 +1,8 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, isValidElement, useRef, } from 'react';
+import { isValidElement, useRef, } from 'react';
 import { cn } from "../internal/cn.js";
+import { slotChildren, warnUnslottedChild } from "../internal/slot-children.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptId } from "../internal/use-id.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
@@ -19,9 +21,9 @@ KptSplitterEnd.kptSplitterSlot = 'end';
  * Dwa panele z przeciąganym uchwytem. `horizontal` stawia je obok siebie, `vertical` jeden pod
  * drugim.
  *
- * Uchwyt to `role="separator"` z wartością (wzorzec WAI-ARIA „window splitter”): strzałki
+ * Uchwyt to `role="separator"` z wartością (wzorzec WAI-ARIA "window splitter"): strzałki
  * przesuwają go o 2%, `Home`/`End` dosuwają do minimum i maksimum. `aria-orientation` opisuje
- * linię uchwytu, nie układ — przy panelach obok siebie linia jest pionowa.
+ * linię uchwytu, nie układ - przy panelach obok siebie linia jest pionowa.
  *
  * @example
  * <KptSplitter startSize={size} onStartSizeChange={setSize}>
@@ -40,16 +42,18 @@ export function KptSplitter({ orientation = 'horizontal', startSize, defaultStar
     });
     let start = null;
     let end = null;
-    Children.forEach(children, (child) => {
-        if (!isValidElement(child))
-            return;
+    for (const child of slotChildren(children)) {
+        if (!isValidElement(child)) {
+            warnUnslottedChild('KptSplitter', child, '<KptSplitter.Start> / <KptSplitter.End>');
+            continue;
+        }
         const slot = child.type?.kptSplitterSlot;
         const content = child.props.children;
         if (slot === 'start')
             start = content;
         else if (slot === 'end')
             end = content;
-    });
+    }
     const clamp = (pct) => Math.min(100 - minSize, Math.max(minSize, Math.round(pct)));
     const onPointerDown = (event) => {
         event.preventDefault();
@@ -58,18 +62,24 @@ export function KptSplitter({ orientation = 'horizontal', startSize, defaultStar
             return;
         // Nasłuch na oknie, nie na uchwycie: przy szybkim ruchu kursor wyprzedza wąski pasek
         // i bez tego przeciąganie urywałoby się po kilku pikselach.
+        // W RTL panel "start" stoi po prawej (flex idzie za kierunkiem pisma), więc mierzymy od prawej.
+        const rtl = getComputedStyle(container).direction === 'rtl';
         const move = (e) => {
             const rect = container.getBoundingClientRect();
             setSize(clamp(orientation === 'horizontal'
-                ? ((e.clientX - rect.left) / rect.width) * 100
+                ? ((rtl ? rect.right - e.clientX : e.clientX - rect.left) / rect.width) * 100
                 : ((e.clientY - rect.top) / rect.height) * 100));
         };
+        // `pointercancel`: dotyk przerwany przez system nie wysyła `pointerup` - bez sprzątania
+        // `pointermove` dalej przesuwałby uchwyt.
         const up = () => {
             window.removeEventListener('pointermove', move);
             window.removeEventListener('pointerup', up);
+            window.removeEventListener('pointercancel', up);
         };
         window.addEventListener('pointermove', move);
         window.addEventListener('pointerup', up);
+        window.addEventListener('pointercancel', up);
     };
     const onKeyDown = (event) => {
         if (event.key === 'Home' || event.key === 'End') {
@@ -85,9 +95,14 @@ export function KptSplitter({ orientation = 'horizontal', startSize, defaultStar
         if (!dir)
             return;
         event.preventDefault();
-        setSize(clamp(size + dir));
+        // W RTL <- przesuwa uchwyt w lewo, czyli powiększa prawy panel "start" - odwrotnie niż w LTR.
+        const horizontal = event.key === 'ArrowLeft' || event.key === 'ArrowRight';
+        const rtl = horizontal && getComputedStyle(event.currentTarget).direction === 'rtl';
+        setSize(clamp(size + (rtl ? -dir : dir)));
     };
-    return (_jsx("div", { className: cn('kpt-splitter-host', className), ...rest, children: _jsxs("div", { ref: containerRef, className: "kpt-splitter", "data-orientation": orientation, children: [_jsx("div", { className: "kpt-splitter__pane", id: startId, style: { flexBasis: `${size}%` }, children: start }), _jsx("div", { className: "kpt-splitter__gutter", role: "separator", tabIndex: 0, "aria-orientation": orientation === 'horizontal' ? 'vertical' : 'horizontal', "aria-valuenow": size, "aria-valuemin": minSize, "aria-valuemax": 100 - minSize, "aria-controls": startId, "aria-label": ariaLabel || t('splitter.resize'), onPointerDown: onPointerDown, onKeyDown: onKeyDown }), _jsx("div", { className: "kpt-splitter__pane", style: { flexBasis: `${100 - size}%` }, children: end })] }) }));
+    return (_jsx("div", { className: cn('kpt-splitter-host', className), ...rest, children: _jsxs("div", { ref: containerRef, className: "kpt-splitter", "data-orientation": orientation, children: [_jsx("div", { className: "kpt-splitter__pane", id: startId, style: { flexBasis: `${size}%` }, children: start }), _jsx("div", { className: "kpt-splitter__gutter", role: "separator", 
+                    // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- separator okna (APG Window Splitter) to fokusowalny widżet ze strzałkami
+                    tabIndex: 0, "aria-orientation": orientation === 'horizontal' ? 'vertical' : 'horizontal', "aria-valuenow": size, "aria-valuemin": minSize, "aria-valuemax": 100 - minSize, "aria-controls": startId, "aria-label": ariaLabel || t('splitter.resize'), onPointerDown: onPointerDown, onKeyDown: onKeyDown }), _jsx("div", { className: "kpt-splitter__pane", style: { flexBasis: `${100 - size}%` }, children: end })] }) }));
 }
 KptSplitter.Start = KptSplitterStart;
 KptSplitter.End = KptSplitterEnd;

package/dist/stepper/llms.txt

@@ -1,38 +1,42 @@
 # KptStepper + KptStep (@konce-pt/react)
 
-A step wizard — a header of numbered steps plus the active step's content.
+A step wizard - a header of numbered steps plus the active step's content.
 Import: `import { KptStepper, useKptStepper } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-stepper-host" style="--kpt-anim-duration:500ms; --kpt-anim-dir:1">
       <ol class="kpt-stepper__header">
         <li class="kpt-stepper__step is-done">
-          <button class="kpt-stepper__marker" aria-label="Step 1: Account, completed">✓</button>
+          <button class="kpt-stepper__marker" aria-label="Step 1: Account, completed">
+            <span class="kpt-stepper__num">1</span><span class="kpt-icon-host kpt-stepper__check"><!-- check --></span>
+          </button>
           <span class="kpt-stepper__label" aria-hidden="true">Account</span>
-          <span class="kpt-stepper__connector"></span>
+          <span class="kpt-stepper__connector" style="--kpt-stepper-line-delay:60ms; --kpt-stepper-line-dur:420ms"></span>
         </li>
-        …
+        ...
       </ol>
-      <div class="kpt-stepper__body"><div class="kpt-stepper__panel">…</div></div>
+      <span class="kpt-stepper__comet" aria-hidden="true"></span>
+      <div class="kpt-stepper__body"><div class="kpt-stepper__panel">...</div></div>
     </div>
 
 ## KptStepper props
 - `activeIndex` / `defaultActiveIndex` / `onActiveIndexChange`
-- `animated`: boolean (default true), `animationDuration`: ms (default 500)
+- `animated`: boolean (default true), `animationDuration`: ms (default 500) - the pace of the whole motion:
+  the content enter, and the line (a segment takes 0.84x, a multi-step jump fits in 1.8x)
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## KptStepper.Step props
-- `label`: string (required); `children` — the step's content
+- `label`: string (required); `children` - the step's content
 
 ## useKptStepper()
-`{ activeIndex, count, next, prev, goTo }` — the replacement for Angular's `#s` + `s.next()`.
+`{ activeIndex, count, next, prev, goTo }` - the replacement for Angular's `#s` + `s.next()`.
 It reads a context the stepper provides around the panel, so it works only in a component
 rendered inside a step (a hook cannot be called in the parent's body) and throws elsewhere.
 `count` lets a step hide "Next" on the last one.
 
 ## The step is a config carrier
 `KptStep` renders `null`; `KptStepper` reads its props and decides what to show, so only the
-active step's content is ever mounted — the same laziness as the `kpt-step` template in Angular.
+active step's content is ever mounted - the same laziness as the `kpt-step` template in Angular.
 
 ## The panel is keyed by index
 `key={active}` forces a remount on every change, otherwise the enter animation would have nothing
@@ -42,7 +46,7 @@ an earlier step animates from the other side.
 ## Examples
     <KptStepper>
       <KptStepper.Step label="Account"><StepNav /></KptStepper.Step>
-      <KptStepper.Step label="Profile">…</KptStepper.Step>
+      <KptStepper.Step label="Profile">...</KptStepper.Step>
     </KptStepper>
 
     function StepNav() {
@@ -55,14 +59,32 @@ an earlier step animates from the other side.
       );
     }
 
+## Motion
+Switching steps reads as colour flowing: the state changes at once (classes, `aria-current`,
+the marker names), but the connector fills from grey to `--kpt-color-primary` with a glowing comet
+running along it, and a marker turns "done" (fills from the centre, the check pops in) only when the
+colour reaches it; the new active step sends out a ring and keeps a soft glow. A jump over several
+steps runs the segments one after another within ~0.9 s; going back retracts them from the end.
+The content of the new step slides in from the side of the move and sharpens out of a blur, the old
+one leaves as a ghost the other way, and the body height changes smoothly.
+
+The timings come from `stepperSchedule` in `@konce-pt/motion` (CSS variables
+`--kpt-stepper-mark-delay`, `--kpt-stepper-line-delay`, `--kpt-stepper-line-dur` on the steps), the comet
+and the ring from `playStepperLight`, the ghost from `preparePanelSwap`. Follows `animated` and `enter`
+from `KptMotionProvider` (`none` - everything switches at once, `fade` - no comet and ring); `enabled: false` and the
+system "reduce motion" setting always win.
+
 ## Tokens
 The active and completed step: `--kpt-color-primary` (marker, connector); the rest
 `--kpt-color-border-strong` and `--kpt-color-on-surface-muted`.
 
 ## Accessibility
 The header is an `<ol>` of real buttons, so every step is reachable with the keyboard and the list
-announces how many there are. Each marker is named from the dictionary — `stepper.step`
-(“Step 2: Delivery”) or `stepper.stepDone` (“…, completed”) — because the visible marker is only a
+announces how many there are. Each marker is named from the dictionary - `stepper.step`
+("Step 2: Delivery") or `stepper.stepDone` ("..., completed") - because the visible marker is only a
 number or a check; the visible label is `aria-hidden` so it is not read twice. The active marker
-carries `aria-current="step"`. After `next()` focus stays where it was — move it into the new step
+carries `aria-current="step"`. After `next()` focus stays where it was - move it into the new step
 yourself when the step is long.
+
+## Inactive content is destroyed
+Switching renders the new panel from scratch (that is what the enter animation starts from), so local state inside the previous one - an unsent file upload, expanded sections, scroll position - is lost. Keep such state in your own model, outside the panel.

package/dist/stepper/stepper.d.ts

@@ -2,14 +2,14 @@ import { type ComponentPropsWithRef, type ReactNode } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptStepperContextValue {
     activeIndex: number;
-    /** Liczba kroków — pozwala treści kroku ukryć „Dalej" na ostatnim. */
+    /** Liczba kroków - pozwala treści kroku ukryć "Dalej" na ostatnim. */
     count: number;
     next: () => void;
     prev: () => void;
     goTo: (index: number) => void;
 }
 /**
- * Sterowanie kreatorem z wnętrza kroku — odpowiednik `#s` + `s.next()` z portu Angulara.
+ * Sterowanie kreatorem z wnętrza kroku - odpowiednik `#s` + `s.next()` z portu Angulara.
  * Poza `<KptStepper>` rzuca błąd, bo bez kreatora nie ma czym sterować.
  *
  * @example
@@ -21,7 +21,7 @@ export interface KptStepProps {
     children?: ReactNode;
 }
 /**
- * Pojedynczy krok. Umieszczaj w `<KptStepper>`. Treść renderuje się leniwie — dopiero gdy krok
+ * Pojedynczy krok. Umieszczaj w `<KptStepper>`. Treść renderuje się leniwie - dopiero gdy krok
  * jest aktywny, tak samo jak szablon `kpt-step` w porcie Angulara.
  */
 export declare function KptStep(_props: Readonly<KptStepProps>): ReactNode;
@@ -37,13 +37,13 @@ export interface KptStepperProps extends Omit<ComponentPropsWithRef<'div'>, 'onC
     children?: ReactNode;
 }
 /**
- * Kreator kroków — nagłówek z numerowanymi krokami i treść aktywnego kroku.
+ * Kreator kroków - nagłówek z numerowanymi krokami i treść aktywnego kroku.
  * Treścią sterują `next()`/`prev()`/`goTo()` z hooka `useKptStepper()`.
  *
  * @example
  * <KptStepper>
- *   <KptStepper.Step label="Konto">…</KptStepper.Step>
- *   <KptStepper.Step label="Profil">…</KptStepper.Step>
+ *   <KptStepper.Step label="Konto">...</KptStepper.Step>
+ *   <KptStepper.Step label="Profil">...</KptStepper.Step>
  * </KptStepper>
  */
 export declare function KptStepper({ activeIndex, defaultActiveIndex, onActiveIndexChange, animated, animationDuration, locale, dictionary, className, style, children, ...rest }: Readonly<KptStepperProps>): import("react").JSX.Element;

package/dist/stepper/stepper.js

@@ -1,12 +1,16 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, createContext, isValidElement, useContext, useState, } from 'react';
+import { createContext, isValidElement, useContext, useLayoutEffect, useRef, useState, } from 'react';
 import { cn } from "../internal/cn.js";
+import { slotChildren, warnUnslottedChild } from "../internal/slot-children.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
+import { playStepperLight, preparePanelSwap, resolveEnterMotion, stepperSchedule, stepperScheduleOptions } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
 const StepperContext = createContext(null);
 /**
- * Sterowanie kreatorem z wnętrza kroku — odpowiednik `#s` + `s.next()` z portu Angulara.
+ * Sterowanie kreatorem z wnętrza kroku - odpowiednik `#s` + `s.next()` z portu Angulara.
  * Poza `<KptStepper>` rzuca błąd, bo bez kreatora nie ma czym sterować.
  *
  * @example
@@ -19,7 +23,7 @@ export function useKptStepper() {
     return context;
 }
 /**
- * Pojedynczy krok. Umieszczaj w `<KptStepper>`. Treść renderuje się leniwie — dopiero gdy krok
+ * Pojedynczy krok. Umieszczaj w `<KptStepper>`. Treść renderuje się leniwie - dopiero gdy krok
  * jest aktywny, tak samo jak szablon `kpt-step` w porcie Angulara.
  */
 export function KptStep(_props) {
@@ -28,13 +32,13 @@ export function KptStep(_props) {
 }
 KptStep.kptStepperSlot = 'step';
 /**
- * Kreator kroków — nagłówek z numerowanymi krokami i treść aktywnego kroku.
+ * Kreator kroków - nagłówek z numerowanymi krokami i treść aktywnego kroku.
  * Treścią sterują `next()`/`prev()`/`goTo()` z hooka `useKptStepper()`.
  *
  * @example
  * <KptStepper>
- *   <KptStepper.Step label="Konto">…</KptStepper.Step>
- *   <KptStepper.Step label="Profil">…</KptStepper.Step>
+ *   <KptStepper.Step label="Konto">...</KptStepper.Step>
+ *   <KptStepper.Step label="Profil">...</KptStepper.Step>
  * </KptStepper>
  */
 export function KptStepper({ activeIndex, defaultActiveIndex = 0, onActiveIndexChange, animated = true, animationDuration = 500, locale, dictionary, className, style, children, ...rest }) {
@@ -45,16 +49,56 @@ export function KptStepper({ activeIndex, defaultActiveIndex = 0, onActiveIndexC
         onChange: onActiveIndexChange,
     });
     const [direction, setDirection] = useState(1);
+    /** Ruch przełączania idzie za `animated` i za `enter` z `KptMotionProvider` (`none` go wyłącza). */
+    const motionConfig = useKptMotion();
+    const motion = animated ? resolveEnterMotion(undefined, motionConfig) : 'none';
+    // Krok sprzed ostatniej zmiany - także przy zmianie z zewnątrz (`activeIndex`). Zapamiętany
+    // w stanie w trakcie renderu (wzorzec "informacja z poprzedniego renderu"), nie w efekcie.
+    const [transition, setTransition] = useState({ from: active, to: active });
+    if (transition.to !== active)
+        setTransition({ from: transition.to, to: active });
+    const rootRef = useRef(null);
+    const bodyRef = useRef(null);
+    /** Duch starej treści przygotowany przed zmianą kroku, odtwarzany po jej wyrenderowaniu. */
+    const pendingSwap = useRef(null);
     const steps = [];
-    Children.forEach(children, (child) => {
-        if (!isValidElement(child) || child.type?.kptStepperSlot !== 'step')
-            return;
+    for (const child of slotChildren(children)) {
+        if (!isValidElement(child) || child.type?.kptStepperSlot !== 'step') {
+            warnUnslottedChild('KptStepper', child, '<KptStep>');
+            continue;
+        }
         steps.push(child.props);
+    }
+    /**
+     * Kiedy widać zmianę każdego znacznika i odcinka linii (`stepperSchedule` z @konce-pt/motion):
+     * kolor płynie po linii i zapala znacznik dopiero, gdy do niego dotrze. Bez ruchu - same zera.
+     */
+    // Tempo linii idzie za `animationDuration` - ten sam czas steruje całym ruchem, nie tylko treścią.
+    const schedule = stepperSchedule(steps.length, motion === 'none' ? active : transition.from, active, stepperScheduleOptions(animationDuration));
+    // Kometa po linii i fala w znaczniku, do którego dociera kolor; duch starej treści - przed malowaniem.
+    useLayoutEffect(() => {
+        const play = pendingSwap.current;
+        pendingSwap.current = null;
+        play?.();
     });
+    useLayoutEffect(() => {
+        const root = rootRef.current;
+        if (!root || motion !== 'spring' || !schedule.direction)
+            return;
+        playStepperLight(schedule, root.querySelector('.kpt-stepper__comet'), Array.from(root.querySelectorAll('.kpt-stepper__connector')), Array.from(root.querySelectorAll('.kpt-stepper__marker')));
+        // Harmonogram liczy się z `transition` - gra raz na zmianę kroku, nie na każdy render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- schedule to pochodna transition i liczby kroków
+    }, [transition, motion]);
     const goTo = (index) => {
         const next = Math.max(0, Math.min(index, steps.length - 1));
+        if (next === active)
+            return;
         // Kierunek karmi `--kpt-anim-dir`, więc panel wjeżdża z tej strony, z której się cofnąłeś.
-        setDirection(next >= active ? 1 : -1);
+        const dir = next > active ? 1 : -1;
+        setDirection(dir);
+        // Stara treść wychodzi jako duch, a pojemnik płynnie zmienia wysokość - mierzone przed zmianą.
+        if (motion !== 'none' && bodyRef.current)
+            pendingSwap.current = preparePanelSwap(bodyRef.current, dir);
         setActive(next);
     };
     const context = {
@@ -64,13 +108,16 @@ export function KptStepper({ activeIndex, defaultActiveIndex = 0, onActiveIndexC
         prev: () => goTo(active - 1),
         goTo,
     };
-    return (_jsxs("div", { className: cn('kpt-stepper-host', className), style: {
+    return (_jsxs("div", { ref: rootRef, className: cn('kpt-stepper-host', className), style: {
             ['--kpt-anim-duration']: `${animated ? animationDuration : 0}ms`,
             ['--kpt-anim-dir']: direction,
             ...style,
-        }, ...rest, children: [_jsx("ol", { className: "kpt-stepper__header", children: steps.map((step, index) => (_jsxs("li", { className: cn('kpt-stepper__step', index === active && 'is-active', index < active && 'is-done'), children: [_jsx("button", { type: "button", className: "kpt-stepper__marker", "aria-current": index === active ? 'step' : undefined, "aria-label": t(index < active ? 'stepper.stepDone' : 'stepper.step', {
+        }, ...rest, children: [_jsx("ol", { className: "kpt-stepper__header", children: steps.map((step, index) => (_jsxs("li", { className: cn('kpt-stepper__step', index === active && 'is-active', index < active && 'is-done'), style: { ['--kpt-stepper-mark-delay']: `${schedule.markers[index] ?? 0}ms` }, children: [_jsxs("button", { type: "button", className: "kpt-stepper__marker", "aria-current": index === active ? 'step' : undefined, "aria-label": t(index < active ? 'stepper.stepDone' : 'stepper.step', {
                                 index: index + 1,
                                 label: step.label,
-                            }), onClick: () => goTo(index), children: index < active ? _jsx(KptIcon, { name: "check" }) : index + 1 }), _jsx("span", { className: "kpt-stepper__label", "aria-hidden": "true", children: step.label }), index < steps.length - 1 ? _jsx("span", { className: "kpt-stepper__connector" }) : null] }, index))) }), _jsx(StepperContext.Provider, { value: context, children: _jsx("div", { className: "kpt-stepper__body", children: steps[active] ? (_jsx("div", { className: "kpt-stepper__panel", children: steps[active].children }, active)) : null }) })] }));
+                            }), onClick: () => goTo(index), children: [_jsx("span", { className: "kpt-stepper__num", children: index + 1 }), _jsx(KptIcon, { className: "kpt-stepper__check", name: "check" })] }), _jsx("span", { className: "kpt-stepper__label", "aria-hidden": "true", children: step.label }), index < steps.length - 1 ? (_jsx("span", { className: "kpt-stepper__connector", style: {
+                                ['--kpt-stepper-line-delay']: `${schedule.lines[index]?.delay ?? 0}ms`,
+                                ['--kpt-stepper-line-dur']: `${schedule.lines[index]?.duration ?? 0}ms`,
+                            } })) : null] }, index))) }), _jsx("span", { className: "kpt-stepper__comet", "aria-hidden": "true" }), _jsx(StepperContext.Provider, { value: context, children: _jsx("div", { className: "kpt-stepper__body", ref: bodyRef, children: steps[active] ? (_jsx("div", { className: "kpt-stepper__panel", children: steps[active].children }, active)) : null }) })] }));
 }
 KptStepper.Step = KptStep;

package/dist/switch/llms.txt

@@ -16,16 +16,17 @@ Import: `import { KptSwitch } from '@konce-pt/react';`
 
 ## Props
 - `label`: string, `labelPosition`: 'start' | 'end' (default 'end')
-- `onLabel`, `offLabel`: string — the state text, swapped on toggle
+- `onLabel`, `offLabel`: string - the state text, swapped on toggle
 - `checked` / `defaultChecked`, `onCheckedChange(checked)`, `onTouch()`
-- `required`, `invalid`, `touched` — as in `KptCheckbox`
-- `hostProps` — props for the `.kpt-switch-host` wrapper
+- `required`, `invalid`, `touched` - as in `KptCheckbox`
+- `toggleMotion`: 'spring' | 'fade' | 'none' (default from `KptMotionProvider`, else `spring`) - see "Toggle motion"
+- `hostProps` - props for the `.kpt-switch-host` wrapper
 - `className` goes to the `.kpt-switch` block; the rest to the native `<input>`
 
 ## The state text needs a controlled value
 `onLabel` and `offLabel` read `checked`, so they only follow the switch in controlled mode.
 Uncontrolled, the value belongs to the DOM and React never learns about a toggle, which would
-freeze the state text on its initial value — use `checked` with `onCheckedChange` whenever you
+freeze the state text on its initial value - use `checked` with `onCheckedChange` whenever you
 show one.
 
 ## Examples
@@ -43,10 +44,19 @@ generated. Inside `KptFormField` the wrapper's `label[for]` points at it and the
 added to `aria-describedby` (merged with your own). Without a wrapper, name it with `aria-label`.
 Inside `kpt-form-field` the switch gets both names: the wrapper label and its own `label`.
 
+## Toggle motion
+`toggleMotion`: `spring` - the thumb travels on a spring and stretches while moving; `fade` - a calm colour and mark transition; `none` - no
+motion. The bounce is started by the change handler, so a control that is checked on load does not
+move. With no value it takes `toggle` from `KptMotionProvider` (default `spring`); `enabled: false` and the
+system "reduce motion" setting always win.
+
 ## Tokens
 `--kpt-color-primary` (the on track), `--kpt-color-muted` (the off track), `--kpt-color-surface`
 (the thumb), `--kpt-motion-duration-fast`.
 
 ## Accessibility
-`role="switch"` on a native checkbox — a screen reader announces on/off instead of
+`role="switch"` on a native checkbox - a screen reader announces on/off instead of
 checked/unchecked. The track and the thumb are `aria-hidden`.
+
+## Read-only and required
+`readOnly` keeps the switch focusable but blocks toggling (`aria-readonly`); `required` sets `aria-required`.

package/dist/switch/switch.d.ts

@@ -1,6 +1,13 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
 import type { KptHostProps } from '../internal/types.ts';
+import { type KptToggleMotion } from '@konce-pt/motion';
 export interface KptSwitchProps extends Omit<ComponentPropsWithRef<'input'>, 'type' | 'required'> {
+    /**
+     * Ruch przełączania: `spring` - kciuk jedzie na sprężynie i rozciąga się w ruchu; `fade` - spokojne przejście koloru i znaku; `none` - bez ruchu.
+     * Bez wartości bierze `toggle` z `KptMotionProvider` (domyślnie `spring`); `enabled={false}` i systemowe
+     * "ogranicz ruch" wyłączają go zawsze.
+     */
+    toggleMotion?: KptToggleMotion;
     /** Etykieta obok przełącznika. */
     label?: string;
     /** Pozycja etykiety względem przełącznika. */
@@ -15,7 +22,7 @@ export interface KptSwitchProps extends Omit<ComponentPropsWithRef<'input'>, 'ty
     invalid?: boolean;
     /** Czy pole było dotknięte; pominięty = stan błędu pokazuje się od razu po `invalid`. */
     touched?: boolean;
-    /** Wygodniejszy odpowiednik `onChange` — dostaje samo zaznaczenie. */
+    /** Wygodniejszy odpowiednik `onChange` - dostaje samo zaznaczenie. */
     onCheckedChange?: (checked: boolean) => void;
     /** Wywoływane na `blur`. */
     onTouch?: () => void;
@@ -27,7 +34,7 @@ export interface KptSwitchProps extends Omit<ComponentPropsWithRef<'input'>, 'ty
  * Przełącznik (switch/toggle). Pod spodem natywny `<input type="checkbox" role="switch">`,
  * więc klawiatura i czytniki ekranu działają bez dodatkowej obsługi.
  *
- * Wariant z tekstem stanu: `onLabel`/`offLabel` — wyświetlany tekst zmienia się przy przełączaniu.
+ * Wariant z tekstem stanu: `onLabel`/`offLabel` - wyświetlany tekst zmienia się przy przełączaniu.
  *
  * Tekst stanu wymaga `checked` (tryb kontrolowany), bo w trybie niekontrolowanym wartość należy
  * do DOM i React o niej nie wie; bez tego etykieta stanu zamarłaby na wartości początkowej.
@@ -36,4 +43,4 @@ export interface KptSwitchProps extends Omit<ComponentPropsWithRef<'input'>, 'ty
  * <KptSwitch name="notifications" label="Powiadomienia" />
  * <KptSwitch checked={on} onCheckedChange={setOn} onLabel="Włączony" offLabel="Wyłączony" />
  */
-export declare function KptSwitch({ label, labelPosition, onLabel, offLabel, required, invalid, touched, onCheckedChange, onTouch, hostProps, className, disabled, checked, onChange, onBlur, children, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, id, ...rest }: Readonly<KptSwitchProps>): import("react").JSX.Element;
+export declare function KptSwitch({ label, labelPosition, onLabel, offLabel, required, invalid, touched, onCheckedChange, onTouch, hostProps, className, disabled, readOnly, onClick, checked, onChange, onBlur, children, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, id, toggleMotion, ...rest }: Readonly<KptSwitchProps>): import("react").JSX.Element;

package/dist/switch/switch.js

@@ -1,12 +1,15 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback } from 'react';
 import { cn } from "../internal/cn.js";
 import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
+import { playPopMotion, resolveToggleMotion } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
 /**
  * Przełącznik (switch/toggle). Pod spodem natywny `<input type="checkbox" role="switch">`,
  * więc klawiatura i czytniki ekranu działają bez dodatkowej obsługi.
  *
- * Wariant z tekstem stanu: `onLabel`/`offLabel` — wyświetlany tekst zmienia się przy przełączaniu.
+ * Wariant z tekstem stanu: `onLabel`/`offLabel` - wyświetlany tekst zmienia się przy przełączaniu.
  *
  * Tekst stanu wymaga `checked` (tryb kontrolowany), bo w trybie niekontrolowanym wartość należy
  * do DOM i React o niej nie wie; bez tego etykieta stanu zamarłaby na wartości początkowej.
@@ -15,18 +18,29 @@ import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
  * <KptSwitch name="notifications" label="Powiadomienia" />
  * <KptSwitch checked={on} onCheckedChange={setOn} onLabel="Włączony" offLabel="Wyłączony" />
  */
-export function KptSwitch({ label = '', labelPosition = 'end', onLabel = '', offLabel = '', required = false, invalid = false, touched, onCheckedChange, onTouch, hostProps, className, disabled = false, checked, onChange, onBlur, children, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, id, ...rest }) {
+export function KptSwitch({ label = '', labelPosition = 'end', onLabel = '', offLabel = '', required = false, invalid = false, touched, onCheckedChange, onTouch, hostProps, className, disabled = false, readOnly = false, onClick, checked, onChange, onBlur, children, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, id, toggleMotion, ...rest }) {
     const field = useKptFieldA11y(id, 'kpt-switch');
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
     const showInvalid = invalid && (touched ?? true);
     const hasStateLabels = !!(onLabel || offLabel);
+    const motion = resolveToggleMotion(toggleMotion, useKptMotion());
     const handleChange = useCallback((event) => {
         onChange?.(event);
         onCheckedChange?.(event.target.checked);
-    }, [onChange, onCheckedChange]);
+        // Kciuk rozciąga się w ruchu - z handlera, nie z CSS, bo reguła na `:checked` grałaby przy starcie.
+        const thumb = event.currentTarget.nextElementSibling?.firstElementChild;
+        if (motion === 'spring' && thumb instanceof HTMLElement)
+            playPopMotion(thumb, 'squash');
+    }, [onChange, onCheckedChange, motion]);
     const handleBlur = useCallback((event) => {
         onBlur?.(event);
         onTouch?.();
     }, [onBlur, onTouch]);
-    return (_jsx("span", { className: cn('kpt-switch-host', hostClassName), ...hostRest, children: _jsxs("label", { className: cn('kpt-switch', disabled && 'kpt-switch--disabled', className), children: [label && labelPosition === 'start' ? (_jsx("span", { className: "kpt-switch__label kpt-switch__label--start", children: label })) : null, _jsx("input", { type: "checkbox", role: "switch", className: "kpt-switch__input", id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), checked: checked, disabled: disabled, "aria-required": required || undefined, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, ...rest }), _jsx("span", { className: "kpt-switch__track", "aria-hidden": "true", children: _jsx("span", { className: "kpt-switch__thumb" }) }), label && labelPosition === 'end' ? _jsx("span", { className: "kpt-switch__label", children: label }) : null, hasStateLabels ? (_jsx("span", { className: cn('kpt-switch__state', checked && 'kpt-switch__state--on'), "aria-hidden": "true", children: checked ? onLabel : offLabel })) : null, children] }) }));
+    return (_jsx("span", { className: cn('kpt-switch-host', hostClassName), ...hostRest, children: _jsxs("label", { className: cn('kpt-switch', disabled && 'kpt-switch--disabled', className), "data-motion": motion, children: [label && labelPosition === 'start' ? (_jsx("span", { className: "kpt-switch__label kpt-switch__label--start", children: label })) : null, _jsx("input", { type: "checkbox", role: "switch", className: "kpt-switch__input", id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), checked: checked, disabled: disabled, "aria-required": required || undefined, "aria-readonly": readOnly || undefined, 
+                    // Natywne `readonly` nie działa na polach wyboru - klik (i Spacja) jest blokowany ręcznie.
+                    onClick: (event) => {
+                        if (readOnly)
+                            event.preventDefault();
+                        onClick?.(event);
+                    }, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, ...rest }), _jsx("span", { className: "kpt-switch__track", "aria-hidden": "true", children: _jsx("span", { className: "kpt-switch__thumb" }) }), label && labelPosition === 'end' ? _jsx("span", { className: "kpt-switch__label", children: label }) : null, hasStateLabels ? (_jsx("span", { className: cn('kpt-switch__state', checked && 'kpt-switch__state--on'), "aria-hidden": "true", children: checked ? onLabel : offLabel })) : null, children] }) }));
 }

package/dist/switch-group/llms.txt

@@ -1,30 +1,30 @@
 # KptSwitchGroup (@konce-pt/react)
 
-A group of switches — mutually exclusive by default, multi-select with `multiple`.
+A group of switches - mutually exclusive by default, multi-select with `multiple`.
 Import: `import { KptSwitchGroup } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-switch-group-host">
       <div class="kpt-switch-group" role="group">
-        <span class="kpt-switch-host kpt-switch-group__item">…KptSwitch…</span>
-        …one per option…
+        <span class="kpt-switch-host kpt-switch-group__item">...KptSwitch...</span>
+        ...one per option...
       </div>
     </div>
 
 ## Props
-- `options`: `KptOption<T>[]` — `{ label, value, disabled? }`
-- `value` / `defaultValue` / `onValueChange` — single select: the option's value or `null`;
+- `options`: `KptOption<T>[]` - `{ label, value, disabled? }`
+- `value` / `defaultValue` / `onValueChange` - single select: the option's value or `null`;
   with `multiple`: an array of the selected values
 - `multiple`: boolean (default false)
 - `orientation`: `'vertical'` (default) | `'horizontal'`
-- `allowDeselect`: boolean (default true) — single select only; in `multiple` mode turning an
+- `allowDeselect`: boolean (default true) - single select only; in `multiple` mode turning an
   option off is always allowed
 - `disabled`, `invalid`, `touched`, `onTouch()`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Single select comes out of the value, not out of the switches
 Every entry is a `KptSwitch` whose `checked` is derived from the group value, so turning one on
-turns the rest off by itself — there is no per-switch state to keep in sync.
+turns the rest off by itself - there is no per-switch state to keep in sync.
 
 That is also why `allowDeselect={false}` needs no code: the handler writes nothing, so React
 re-applies the controlled `checked` and the switch snaps back on.
@@ -37,7 +37,7 @@ re-applies the controlled `checked` and the switch snaps back on.
 ## Screen reader and keyboard
 `aria-invalid` is not supported on `role="group"`, so the error state is carried by each switch. In
 single mode the switches are mutually exclusive and nothing announces that turning one on turned
-another off — for a single choice prefer `KptRadioGroup`.
+another off - for a single choice prefer `KptRadioGroup`.
 
 ## Label and description
 `id` goes to the focusable element, not the host; without one it comes from `KptFormField` or is
@@ -52,3 +52,6 @@ Layout only: `--kpt-space-2` (vertical gap) and `--kpt-space-4` (horizontal). Th
 ## Accessibility
 `role="group"` with `aria-invalid` once the field is touched; every entry keeps the native
 checkbox of `KptSwitch`, so keyboard and screen readers work with no extra handling.
+
+## Read-only and required
+`readOnly` is passed to every switch. With `allowDeselect=false` turning the active switch off puts it back on - before, the switch looked off while the group value said it was on.

package/dist/switch-group/switch-group.d.ts

@@ -6,22 +6,24 @@ export interface KptSwitchGroupProps<T> extends Omit<ComponentPropsWithRef<'div'
     value?: T | T[] | null;
     defaultValue?: T | T[] | null;
     onValueChange?: (value: T | T[] | null) => void;
-    /** Wielokrotny wybór — wartością staje się tablica `T[]`. */
+    /** Wielokrotny wybór - wartością staje się tablica `T[]`. */
     multiple?: boolean;
     orientation?: 'vertical' | 'horizontal';
     /** Czy wyłączenie aktywnej opcji zeruje wartość. Dotyczy tylko trybu pojedynczego. */
     allowDeselect?: 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 - przełączniki widać, nie da się ich zmienić. */
+    readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
     onTouch?: () => void;
 }
 /**
- * Grupa przełączników. Domyślnie wzajemnie wykluczających się — włączenie jednego wyłącza
+ * Grupa przełączników. Domyślnie wzajemnie wykluczających się - włączenie jednego wyłącza
  * pozostałe; z `multiple` wartością jest tablica zaznaczonych opcji.
  *
  * Renderuje `KptSwitch`, więc dziedziczy jego wygląd, tokeny i obsługę klawiatury.
@@ -30,4 +32,4 @@ export interface KptSwitchGroupProps<T> extends Omit<ComponentPropsWithRef<'div'
  * <KptSwitchGroup options={plans} value={plan} onValueChange={setPlan} />
  * <KptSwitchGroup multiple options={tags} value={selected} onValueChange={setSelected} />
  */
-export declare function KptSwitchGroup<T>({ options, value, defaultValue, onValueChange, multiple, orientation, allowDeselect, id, ariaLabel, disabled, invalid, touched, onTouch, className, ...rest }: Readonly<KptSwitchGroupProps<T>>): import("react").JSX.Element;
+export declare function KptSwitchGroup<T>({ options, value, defaultValue, onValueChange, multiple, orientation, allowDeselect, id, ariaLabel, disabled, readOnly, invalid, touched, onTouch, className, ...rest }: Readonly<KptSwitchGroupProps<T>>): import("react").JSX.Element;