@konce-pt/react 0.16.1 → 0.18.0

package/dist/galleria/galleria.js

@@ -1,6 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { attachDragScroll, playGallerySlide, resolveEnterMotion, revealThumb, scrollStrip, stopGallerySlide, trackStripEdges, } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
@@ -15,6 +17,12 @@ const NAV_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'Home', 'End']);
  * aktywną. Miniatura ma nazwę z `alt` obrazu i `aria-current` na aktywnej, a zmiana obrazu jest
  * ogłaszana uprzejmie ("Obraz 2 z 4: ...") - dopiero po działaniu użytkownika, nie przy starcie.
  *
+ * Ruch: nowe zdjęcie wjeżdża w kierunku zmiany na sprężynie, a poprzednie cofa się wolniej
+ * i przygasa (paralaksa); rodzaj z `enter` w `KptMotionProvider`, przy "ogranicz ruch" - przenikanie.
+ * Pasek miniatur nie ma paska przewijania: przewija się przeciąganiem (mysz, pióro, palec)
+ * albo strzałkami paska, krawędzie gasną tam, gdzie jest coś dalej, a aktywna miniatura
+ * zawsze wraca do widoku.
+ *
  * @example
  * <KptGalleria items={photos} activeIndex={index} onActiveIndexChange={setIndex} />
  */
@@ -31,8 +39,66 @@ export function KptGalleria({ items = [], activeIndex, defaultActiveIndex = 0, o
     const [userMoved, setUserMoved] = useState(false);
     const thumbsRef = useRef([]);
     const rootRef = useRef(null);
+    const stageRef = useRef(null);
+    const imageRef = useRef(null);
+    const stripRef = useRef(null);
+    const stripWrapRef = useRef(null);
+    const edgesRef = useRef(null);
+    /** Co było pokazane przy poprzednim renderze - z tego wynika kierunek i duch poprzedniego zdjęcia. */
+    const shownRef = useRef(null);
+    const motion = resolveEnterMotion(undefined, useKptMotion());
     const current = items[active] ?? null;
     const last = items.length - 1;
+    const currentSrc = current?.src ?? '';
+    // Zmiana zdjęcia: po wpisaniu nowego `src` do DOM, przed malowaniem. Pierwszy render i wymiana
+    // listy bez zmiany indeksu nie grają ruchu - przesuw ilustruje przejście, nie ładowanie.
+    useLayoutEffect(() => {
+        const prev = shownRef.current;
+        shownRef.current = { index: active, src: currentSrc };
+        const strip = stripRef.current;
+        const thumb = thumbsRef.current[active];
+        // Start na dalekim zdjęciu: pasek od razu pokazuje aktywną miniaturę, bez przewijania na oczach.
+        if (!prev) {
+            if (strip && thumb)
+                revealThumb(strip, thumb, false);
+            return;
+        }
+        if (prev.index === active)
+            return;
+        const stage = stageRef.current;
+        const image = imageRef.current;
+        if (stage && image && prev.src && prev.src !== currentSrc) {
+            playGallerySlide({ stage, image, previousSrc: prev.src, direction: active > prev.index ? 1 : -1, motion });
+        }
+        if (strip && thumb)
+            revealThumb(strip, thumb);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- ruch czyta konfigurację z chwili zmiany; sama zmiana konfiguracji nie przesuwa zdjęcia
+    }, [active, currentSrc]);
+    // Pasek: krawędzie i przeciąganie - podpinane, gdy pasek istnieje, i odpinane razem z nim.
+    useEffect(() => {
+        const strip = stripRef.current;
+        const wrap = stripWrapRef.current;
+        if (!strip || !wrap)
+            return;
+        const edges = trackStripEdges(strip, wrap);
+        edgesRef.current = edges;
+        const detach = attachDragScroll(strip);
+        return () => {
+            edges.dispose();
+            detach();
+            edgesRef.current = null;
+        };
+    }, [showThumbnails]);
+    // Nowa lista miniatur zmienia szerokość paska bez zmiany jego rozmiaru - krawędzie liczymy na nowo.
+    useEffect(() => edgesRef.current?.update(), [items]);
+    useEffect(() => {
+        const stage = stageRef.current;
+        const image = imageRef;
+        return () => {
+            if (stage)
+                stopGallerySlide(stage, image.current);
+        };
+    }, []);
     const select = (index) => {
         if (last < 0)
             return active;
@@ -57,7 +123,7 @@ export function KptGalleria({ items = [], activeIndex, defaultActiveIndex = 0, o
     };
     const position = t('galleria.position', { index: active + 1, total: items.length });
     const announcement = userMoved ? (current?.alt ? `${position}: ${current.alt}` : position) : '';
-    return (_jsx("div", { className: cn('kpt-galleria-host', className), ...rest, children: _jsxs("div", { ref: rootRef, className: "kpt-galleria", onKeyDown: onKeyDown, children: [_jsxs("div", { className: "kpt-galleria__stage", children: [_jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--prev", "aria-disabled": active <= 0 || undefined, "aria-label": t('common.previous'), onClick: () => select(active - 1), children: _jsx(KptIcon, { name: "chevron-left" }) }), current ? _jsx("img", { className: "kpt-galleria__image", src: current.src, alt: current.alt || '' }) : null, _jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--next", "aria-disabled": active >= last || undefined, "aria-label": t('common.next'), onClick: () => select(active + 1), children: _jsx(KptIcon, { name: "chevron-right" }) })] }), showThumbnails ? (_jsx("div", { className: "kpt-galleria__thumbs", children: items.map((item, index) => (_jsx("button", { ref: (el) => {
-                            thumbsRef.current[index] = el;
-                        }, type: "button", className: cn('kpt-galleria__thumb', index === active && 'is-active'), "aria-current": index === active ? 'true' : undefined, "aria-label": item.alt || t('galleria.image', { index: index + 1 }), onClick: () => select(index), children: _jsx("img", { src: item.thumbnail || item.src, alt: "" }) }, index))) })) : null, _jsx("span", { className: "kpt-galleria__live", "aria-live": "polite", children: announcement })] }) }));
+    return (_jsx("div", { className: cn('kpt-galleria-host', className), ...rest, children: _jsxs("div", { ref: rootRef, className: "kpt-galleria", onKeyDown: onKeyDown, children: [_jsxs("div", { ref: stageRef, className: "kpt-galleria__stage", children: [_jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--prev", "aria-disabled": active <= 0 || undefined, "aria-label": t('common.previous'), onClick: () => select(active - 1), children: _jsx(KptIcon, { name: "chevron-left" }) }), current ? _jsx("img", { ref: imageRef, className: "kpt-galleria__image", src: current.src, alt: current.alt || '' }) : null, _jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--next", "aria-disabled": active >= last || undefined, "aria-label": t('common.next'), onClick: () => select(active + 1), children: _jsx(KptIcon, { name: "chevron-right" }) })] }), showThumbnails ? (_jsxs("div", { ref: stripWrapRef, className: "kpt-galleria__strip", children: [_jsx("button", { type: "button", className: "kpt-galleria__scroll kpt-galleria__scroll--back", tabIndex: -1, "aria-label": t('galleria.scrollBack'), onClick: () => stripRef.current && scrollStrip(stripRef.current, -1), children: _jsx(KptIcon, { name: "chevron-left" }) }), _jsx("div", { ref: stripRef, className: "kpt-galleria__thumbs", children: items.map((item, index) => (_jsx("button", { ref: (el) => {
+                                    thumbsRef.current[index] = el;
+                                }, type: "button", className: cn('kpt-galleria__thumb', index === active && 'is-active'), "aria-current": index === active ? 'true' : undefined, "aria-label": item.alt || t('galleria.image', { index: index + 1 }), onClick: () => select(index), children: _jsx("img", { src: item.thumbnail || item.src, alt: "", draggable: false }) }, index))) }), _jsx("button", { type: "button", className: "kpt-galleria__scroll kpt-galleria__scroll--forward", tabIndex: -1, "aria-label": t('galleria.scrollForward'), onClick: () => stripRef.current && scrollStrip(stripRef.current, 1), children: _jsx(KptIcon, { name: "chevron-right" }) })] })) : null, _jsx("span", { className: "kpt-galleria__live", "aria-live": "polite", children: announcement })] }) }));
 }

package/dist/galleria/llms.txt

@@ -11,8 +11,12 @@ Import: `import { KptGalleria, type KptGalleriaItem } from '@konce-pt/react';`
           <img class="kpt-galleria__image" src="..." alt="Mountain lake">
           <button class="kpt-galleria__nav kpt-galleria__nav--next" aria-label="Next">...</button>
         </div>
-        <div class="kpt-galleria__thumbs">
-          <button class="kpt-galleria__thumb is-active" aria-current="true" aria-label="Mountain lake"><img src="..." alt=""></button>...
+        <div class="kpt-galleria__strip" data-scroll-end>
+          <button class="kpt-galleria__scroll kpt-galleria__scroll--back" tabindex="-1" aria-label="Scroll thumbnails back">...</button>
+          <div class="kpt-galleria__thumbs">
+            <button class="kpt-galleria__thumb is-active" aria-current="true" aria-label="Mountain lake"><img src="..." alt="" draggable="false"></button>...
+          </div>
+          <button class="kpt-galleria__scroll kpt-galleria__scroll--forward" tabindex="-1" aria-label="Scroll thumbnails forward">...</button>
         </div>
         <span class="kpt-galleria__live" aria-live="polite">Image 2 of 4: Pine forest</span>
       </div>
@@ -43,6 +47,29 @@ The arrows use `common.previous` / `common.next`, the thumbnails without `alt` `
 Anywhere inside the gallery, `ArrowLeft`/`ArrowRight` move to the neighbouring image (reversed in
 RTL) and `Home`/`End` to the first/last. When focus is on a thumbnail, it follows the active one.
 
+## Motion and the thumbnail strip
+Changing the image slides the new one in from the side of travel on a soft spring, while the
+previous one - a temporary `<img class="kpt-galleria__ghost">` under it - drifts back slower and
+dims (parallax). The kind comes from `enter` in `KptMotionProvider`: `spring` (default), `fade` (a short
+cross-fade) or `none`; with the system "reduce motion" setting it only cross-fades. The first
+render and a new `items` list at the same index do not animate.
+
+The strip has no scrollbar. It scrolls by dragging (mouse and pen; a touch screen scrolls natively),
+with the wheel or with two small strip arrows that appear only on the side there is more to see -
+the strip fades out on that edge too (`data-scroll-start` / `data-scroll-end` on
+`.kpt-galleria__strip`). A move under 5 px is still a click on a thumbnail; after a real drag the
+click is swallowed and the strip glides on with inertia. The active thumbnail always returns into
+view, and only as far as needed. The strip arrows are `tabindex="-1"`: from the keyboard the gallery
+arrows drive the strip. All of it lives in `@konce-pt/motion` (`playGallerySlide`, `attachDragScroll`,
+`revealThumb`, `trackStripEdges`), shared by both ports.
+
+## Size
+The stage has a fixed aspect ratio and the image fills it, so the gallery takes the full width of
+its container and does not jump in height between images. An image with different proportions is
+cropped (`object-fit: cover`). Two custom properties change it, set on the gallery or any ancestor:
+- `--kpt-galleria-aspect-ratio` (default `16 / 9`), e.g. `4 / 3` or `1`
+- `--kpt-galleria-fit` (default `cover`); `contain` shows the whole image with the stage colour around it
+
 ## Tokens
 The stage `--kpt-color-muted`; the active thumbnail `--kpt-color-primary`; the arrows `--kpt-color-surface` (85% via `color-mix`, solid on hover) / `--kpt-color-on-surface` with `--kpt-elevation-2`.
 

package/dist/image/image.d.ts

@@ -16,6 +16,10 @@ export interface KptImageProps extends Omit<ComponentPropsWithRef<'div'>, 'onCli
  * stronę i górną warstwę. Na czas podglądu blokujemy przewijanie dokumentu, a po zamknięciu
  * fokus wraca na miniaturę.
  *
+ * Ruch: zdjęcie wylatuje z miniatury i ląduje na środku na sprężynie, a przy zamknięciu (`x`,
+ * `Escape`, tło) wraca do niej, zanim okno się zamknie. Rodzaj ruchu bierze z `enter`
+ * w `KptMotionProvider` (`spring` / `fade` / `none`); przy "ogranicz ruch" podgląd tylko się przenika.
+ *
  * @example
  * <KptImage src="/foto.jpg" alt="Zdjęcie" preview width="240px" />
  */

package/dist/image/image.js

@@ -1,6 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
+import { playZoomClose, playZoomOpen, resolveEnterMotion, stopZoomMotion } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
 import { cn } from "../internal/cn.js";
 import { kptLockScroll } from "../internal/scroll-lock.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
@@ -13,6 +15,10 @@ import { KptIcon } from "../icon/icon.js";
  * stronę i górną warstwę. Na czas podglądu blokujemy przewijanie dokumentu, a po zamknięciu
  * fokus wraca na miniaturę.
  *
+ * Ruch: zdjęcie wylatuje z miniatury i ląduje na środku na sprężynie, a przy zamknięciu (`x`,
+ * `Escape`, tło) wraca do niej, zanim okno się zamknie. Rodzaj ruchu bierze z `enter`
+ * w `KptMotionProvider` (`spring` / `fade` / `none`); przy "ogranicz ruch" podgląd tylko się przenika.
+ *
  * @example
  * <KptImage src="/foto.jpg" alt="Zdjęcie" preview width="240px" />
  */
@@ -21,32 +27,77 @@ export function KptImage({ src, alt = '', width = null, preview = false, locale,
     const [open, setOpen] = useState(false);
     const dialogRef = useRef(null);
     const triggerRef = useRef(null);
+    const fullRef = useRef(null);
+    const closeRef = useRef(null);
+    const closeTimer = useRef(null);
+    const motion = resolveEnterMotion(undefined, useKptMotion());
+    const zoomElements = () => {
+        const thumb = triggerRef.current, image = fullRef.current, dialog = dialogRef.current;
+        return thumb && image && dialog ? { thumb, image, dialog, close: closeRef.current } : null;
+    };
     useEffect(() => {
         const el = dialogRef.current;
         if (!el || !open)
             return;
-        if (!el.open)
+        if (!el.open) {
             el.showModal();
+            // Tuż po showModal(), przed malowaniem - pierwsza klatka stoi już na miniaturze.
+            const els = zoomElements();
+            if (els)
+                playZoomOpen(els, motion);
+        }
         const releaseScroll = kptLockScroll();
         return () => {
             releaseScroll();
             if (el.open)
                 el.close();
         };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- ruch czyta stan z chwili otwarcia; zmiana konfiguracji nie otwiera okna ponownie
     }, [open]);
+    // Zegar zamknięcia nie może przeżyć komponentu.
+    useEffect(() => () => {
+        if (closeTimer.current)
+            clearTimeout(closeTimer.current);
+    }, []);
     const style = width ? { width } : undefined;
     if (!preview) {
         return (_jsx("div", { className: cn('kpt-image-host', className), ...rest, children: _jsx("div", { className: "kpt-image", style: style, children: _jsx("img", { className: "kpt-image__img", src: src, alt: alt }) }) }));
     }
-    // `close` przychodzi z każdej drogi: `x`, `Escape`, tło.
+    // Zamknięcie z `x`, `Escape` i tła: najpierw powrót zdjęcia do miniatury, potem okno.
+    const requestClose = () => {
+        if (closeTimer.current)
+            return;
+        const els = zoomElements();
+        const ms = els ? playZoomClose(els, motion) : 0;
+        if (ms === 0) {
+            dialogRef.current?.close();
+            return;
+        }
+        closeTimer.current = setTimeout(() => {
+            closeTimer.current = null;
+            dialogRef.current?.close();
+        }, ms);
+    };
+    // `Escape` zamknąłby okno od razu - przejmujemy je, żeby zdjęcie zdążyło wrócić.
+    const onCancel = (event) => {
+        event.preventDefault();
+        requestClose();
+    };
+    // `close` przychodzi z każdej drogi (także wymuszonej przez przeglądarkę) - tu sprzątamy.
     const onClosed = () => {
+        if (closeTimer.current)
+            clearTimeout(closeTimer.current);
+        closeTimer.current = null;
+        const els = zoomElements();
+        if (els)
+            stopZoomMotion(els);
         setOpen(false);
         triggerRef.current?.focus();
     };
     // Okno wypełnia cały ekran, więc kliknięcie w nie samo (a nie w zdjęcie) to kliknięcie w tło.
     const onDialogClick = (event) => {
         if (event.target === event.currentTarget)
-            event.currentTarget.close();
+            requestClose();
     };
-    return (_jsxs("div", { className: cn('kpt-image-host', className), ...rest, children: [_jsxs("button", { ref: triggerRef, type: "button", className: "kpt-image kpt-image--preview", "aria-haspopup": "dialog", "aria-label": alt ? t('image.previewOf', { alt }) : t('image.preview'), style: style, onClick: () => setOpen(true), children: [_jsx("img", { className: "kpt-image__img", src: src, alt: "" }), _jsx("span", { className: "kpt-image__mask", "aria-hidden": "true", children: _jsx(KptIcon, { name: "zoom-in" }) })] }), _jsxs("dialog", { ref: dialogRef, className: "kpt-image__overlay", "aria-label": alt || t('image.preview'), onClose: onClosed, onClick: onDialogClick, children: [_jsx("button", { type: "button", className: "kpt-image__close", onClick: () => dialogRef.current?.close(), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) }), _jsx("img", { className: "kpt-image__full", src: src, alt: alt, loading: "lazy" })] })] }));
+    return (_jsxs("div", { className: cn('kpt-image-host', className), ...rest, children: [_jsxs("button", { ref: triggerRef, type: "button", className: "kpt-image kpt-image--preview", "aria-haspopup": "dialog", "aria-label": alt ? t('image.previewOf', { alt }) : t('image.preview'), style: style, onClick: () => setOpen(true), children: [_jsx("img", { className: "kpt-image__img", src: src, alt: "" }), _jsx("span", { className: "kpt-image__mask", "aria-hidden": "true", children: _jsx(KptIcon, { name: "zoom-in" }) })] }), _jsxs("dialog", { ref: dialogRef, className: "kpt-image__overlay", "aria-label": alt || t('image.preview'), onClose: onClosed, onCancel: onCancel, onClick: onDialogClick, children: [_jsx("button", { ref: closeRef, type: "button", className: "kpt-image__close", onClick: requestClose, "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) }), _jsx("img", { ref: fullRef, className: "kpt-image__full", src: src, alt: alt })] })] }));
 }

package/dist/image/llms.txt

@@ -40,6 +40,21 @@ only add noise for a screen reader.
 ## i18n
 The thumbnail is named from `image.previewOf` (`{alt}`) or `image.preview`; the close button from `common.close`.
 
+## Motion
+The preview flies out of the thumbnail and lands in the middle on a soft spring; the corners keep the
+thumbnail radius in flight and the thumbnail is empty while the photo is out. Closing - the x button,
+`Escape` or a click on the backdrop - sends it back into the thumbnail before the dialog closes
+(`Escape` is taken over through the dialog's `cancel` event). The kind comes from `enter` in the
+motion config: `spring` (default), `fade` (cross-fade) or `none`. With the system "reduce motion"
+setting the preview only cross-fades. The flight lives in `@konce-pt/motion` (`playZoomOpen`,
+`playZoomClose`), shared by both ports.
+
+## Preview size
+The full-size photo keeps its proportions and is limited to 80% of the window height and 90% of its
+width, so a portrait photo fits whole with a margin above and below, and the x button does not cover
+it. Change the limits with `--kpt-image-preview-max-height` (default `80vh`) and
+`--kpt-image-preview-max-width` (default `90vw`).
+
 ## Tokens
 The radius `--kpt-radius-md`; the backdrop and the hover mask `--kpt-color-overlay-scrim`; the x button and the magnifier disc `--kpt-color-surface` / `--kpt-color-on-surface` with `--kpt-elevation-2`.
 

package/dist/input/input.d.ts

@@ -1,9 +1,10 @@
 import { type ComponentPropsWithRef } from 'react';
 import type { KptSpeechMode } from '@konce-pt/speech';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import { type KptSpeechColor } from '../speech/speech-button.tsx';
 import type { KptHostProps } from '../internal/types.ts';
 export type KptInputType = 'text' | 'email' | 'password' | 'number' | 'search' | 'tel' | 'url' | 'time';
-export interface KptInputProps extends Omit<ComponentPropsWithRef<'input'>, 'type' | 'required'> {
+export interface KptInputProps extends Omit<ComponentPropsWithRef<'input'>, 'type' | 'required'>, KptI18nOverrides {
     /** Typ pola. */
     type?: KptInputType;
     /**
@@ -36,6 +37,16 @@ export interface KptInputProps extends Omit<ComponentPropsWithRef<'input'>, 'typ
      * mikrofonu, a dyktowanie kończy się po jednej wypowiedzi (wzorzec wyszukiwarki).
      */
     speechMode?: KptSpeechMode;
+    /**
+     * Przycisk czyszczenia na końcu pola. Bez ustawienia - włączony tylko dla `type="search"`,
+     * gdzie zastępuje systemowe "x" (ukryte zawsze, także przy `clearable={false}`).
+     */
+    clearable?: boolean;
+    /**
+     * Ikona z rejestru na początku pola (`search`, `mail`...). Dekoracyjna - nazwę pola daje etykieta
+     * albo `aria-label`, więc ikona nie trafia do drzewa dostępności.
+     */
+    icon?: string;
 }
 /**
  * Pole tekstowe Koncept UI. Renderuje natywny `<input>` w hoście `.kpt-input-host`.
@@ -51,4 +62,4 @@ export interface KptInputProps extends Omit<ComponentPropsWithRef<'input'>, 'typ
  * <KptInput name="email" type="email" defaultValue="" />
  * <KptInput value={email} onValueChange={setEmail} invalid={!ok} touched={blurred} />
  */
-export declare function KptInput({ type, required, invalid, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech, speechLang, speechColor, speechMode, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptInputProps>): import("react").JSX.Element;
+export declare function KptInput({ type, required, invalid, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech, speechLang, speechColor, speechMode, clearable, icon, onKeyDown, locale, dictionary, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptInputProps>): import("react").JSX.Element;

package/dist/input/input.js

@@ -1,11 +1,21 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState, } from 'react';
+import { useKptMessages } from "../i18n/i18n-context.js";
+import { KptIcon } from "../icon/icon.js";
 import { cn } from "../internal/cn.js";
 import { composeRefs } from "../internal/compose-refs.js";
 import { KptSpeechButton } from "../speech/speech-button.js";
 import { useKptSpeechRecognition } from "../speech/use-speech-recognition.js";
 import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
+/**
+ * Wpisuje wartość setterem z prototypu i wysyła `input`. Samo `el.value = ''` React by połknął:
+ * jego tracker wartości uznałby zdarzenie za echo i nie wywołałby `onChange`.
+ */
+function setFieldValue(field, value) {
+    Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set?.call(field, value);
+    field.dispatchEvent(new Event('input', { bubbles: true }));
+}
 /**
  * Pole tekstowe Koncept UI. Renderuje natywny `<input>` w hoście `.kpt-input-host`.
  *
@@ -20,7 +30,7 @@ import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
  * <KptInput name="email" type="email" defaultValue="" />
  * <KptInput value={email} onValueChange={setEmail} invalid={!ok} touched={blurred} />
  */
-export function KptInput({ type = 'text', required = false, invalid = false, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech = false, speechLang, speechColor, speechMode = 'insert', 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }) {
+export function KptInput({ type = 'text', required = false, invalid = false, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech = false, speechLang, speechColor, speechMode = 'insert', clearable, icon, onKeyDown, locale, dictionary, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }) {
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
     const field = useKptFieldA11y(id, 'kpt-input');
     const innerRef = useRef(null);
@@ -38,13 +48,49 @@ export function KptInput({ type = 'text', required = false, invalid = false, tou
     // Stan nieprawidłowy pokazujemy dopiero po dotknięciu pola - jak natywne `:user-invalid`.
     // Bez `touched` nie ma czego bramkować, więc decyduje samo `invalid`.
     const showInvalid = invalid && (touched ?? true);
+    const { t } = useKptMessages({ locale, dictionary });
+    // W trybie niekontrolowanym wartość należy do DOM i React jej nie widzi - to, czy jest co
+    // czyścić, trzymamy osobno. W kontrolowanym decyduje `value`.
+    const [filledUncontrolled, setFilledUncontrolled] = useState(() => String(rest.defaultValue ?? '') !== '');
+    const filled = rest.value === undefined ? filledUncontrolled : String(rest.value) !== '';
+    const showClear = (clearable ?? type === 'search') && filled && !rest.disabled && !rest.readOnly;
+    // Reset formularza (`form.reset()`, a w React 19 także po `<form action>`) przywraca wartość bez
+    // zdarzenia `input` - stan "jest co czyścić" odczytujemy wtedy z pola, gdy reset już się wykona.
+    useEffect(() => {
+        const form = innerRef.current?.form;
+        if (!form)
+            return;
+        const onReset = () => {
+            queueMicrotask(() => setFilledUncontrolled((innerRef.current?.value ?? '') !== ''));
+        };
+        form.addEventListener('reset', onReset);
+        return () => form.removeEventListener('reset', onReset);
+    }, []);
     const handleChange = useCallback((event) => {
+        setFilledUncontrolled(event.target.value !== '');
         onChange?.(event);
         onValueChange?.(event.target.value);
     }, [onChange, onValueChange]);
+    /** Czyści zdarzeniem `input` - przechodzi przez `onChange` jak wpisane, w obu trybach. */
+    const clear = () => {
+        const field = innerRef.current;
+        if (!field)
+            return;
+        setFieldValue(field, '');
+        field.focus();
+    };
+    /** Escape czyści pełne pole i nie idzie dalej - pierwszy nie zamyka okna, w którym pole stoi. */
+    const handleKeyDown = (event) => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented || event.key !== 'Escape' || !showClear)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        clear();
+    };
     const handleBlur = useCallback((event) => {
         onBlur?.(event);
         onTouch?.();
     }, [onBlur, onTouch]);
-    return (_jsxs("span", { className: cn('kpt-input-host', hostClassName), "data-speech": speechState, ...hostRest, children: [_jsx("input", { className: cn('kpt-input__field', className), id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), type: type, "aria-required": required || undefined, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, ref: composeRefs(innerRef, ref), ...rest }), speech ? (_jsx(KptSpeechButton, { listeningColor: speechColor, speech: mic, size: "sm", unsupported: "hide", disabled: !!rest.disabled || !!rest.readOnly, hostProps: { className: 'kpt-input__speech' } })) : null] }));
+    return (_jsxs("span", { className: cn('kpt-input-host', hostClassName), "data-speech": speechState, "data-clear": showClear ? '' : undefined, "data-icon": icon ? '' : undefined, ...hostRest, children: [icon ? _jsx(KptIcon, { className: "kpt-input__icon", name: icon }) : null, _jsx("input", { className: cn('kpt-input__field', className), id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), type: type, "aria-required": required || undefined, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, onKeyDown: handleKeyDown, ref: composeRefs(innerRef, ref), ...rest }), showClear ? (_jsx("button", { type: "button", className: "kpt-input__clear", tabIndex: -1, "aria-label": t('input.clear'), onMouseDown: (event) => event.preventDefault(), onClick: clear, children: _jsx(KptIcon, { name: "x" }) })) : null, speech ? (_jsx(KptSpeechButton, { listeningColor: speechColor, speech: mic, size: "sm", unsupported: "hide", disabled: !!rest.disabled || !!rest.readOnly, hostProps: { className: 'kpt-input__speech' } })) : null] }));
 }

package/dist/input/llms.txt

@@ -15,6 +15,10 @@ Import: `import { KptInput } from '@konce-pt/react';`
 - `onTouch()` - fires on blur, the moment the field becomes touched
 - `required`: boolean - see the note below
 - `invalid`: boolean, `touched`: boolean - the error state
+- `clearable`: boolean (default: `true` only for `type="search"`) - a clear button, see "Clear button"
+- `icon`: string - a registry icon at the start of the field (`search`, `mail`...). Decorative: the field's
+  name comes from the label or the aria label, so the icon stays out of the accessibility tree; a click on it
+  lands in the field
 - `hostProps` - props for the `.kpt-input-host` wrapper
 - `className`, `ref`, `name`, `placeholder`, `autoComplete` and every other `<input>` prop go to
   the inner `<input>`
@@ -51,6 +55,22 @@ configuration. An explicit `id` prop still wins.
 generated. Inside `KptFormField` the wrapper's `label[for]` points at it and the hint or error is
 added to `aria-describedby` (merged with your own). Without a wrapper, name it with `aria-label`.
 
+## Clear button
+`type="search"` gets a clear button at the end of the field as soon as it has a value; `clearable`
+turns it on for any other type, `clearable={false}` turns it off. The browser's own "x"
+(`::-webkit-search-cancel-button`) is always hidden - Chromium and Safari draw it differently and
+Firefox not at all. The button is hidden while the field is empty, disabled or read-only.
+
+Clearing dispatches a real `input` event, so the value goes through the same path as typed text,
+and the focus stays in the field. The button is `tabindex="-1"` (like the `KptInputNumber`
+steppers); from the keyboard `Escape` clears a filled field and stops the event, so the first
+`Escape` does not close the dialog the field sits in. Its name comes from `input.clear` in the
+dictionary. The host gets `data-clear` while the button is visible.
+
+    <KptInput type="search" value={query} onValueChange={setQuery} />
+    <KptInput clearable value={coupon} onValueChange={setCoupon} />
+    <KptInput type="search" icon="search" value={query} onValueChange={setQuery} />
+
 ## Tokens
 `--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`.
 

package/dist/popover/llms.txt

@@ -17,6 +17,9 @@ Import: `import { KptPopover } from '@konce-pt/react';`
 - `placement`: 'bottom' (default) | 'top' - the preferred side; it flips when there is no room
 - `maxWidth`: string - the panel's maximum width, any CSS length (`'24rem'`; default `20rem`). The panel is
   never wider than the window minus the 8 px overlay margin
+- `ariaLabel`: string - the accessible name of the panel (`role="dialog"`); give one whenever the panel has
+  no visible heading. It names the panel, not the host - `aria-label` in the rest props would land on the
+  host `<span>`
 - `className`, `ref` and every other `<span>` prop go to the host
 
 ## The panel is a portal

package/dist/public-api.d.ts

@@ -5,7 +5,7 @@ export type { KptToolbarProps } from './toolbar/toolbar.tsx';
 export { KptSidenav, KptSidenavFooter } from './sidenav/sidenav.tsx';
 export type { KptSidenavProps } from './sidenav/sidenav.tsx';
 export { KptTabs, KptTab } from './tabs/tabs.tsx';
-export type { KptTabProps, KptTabsProps } from './tabs/tabs.tsx';
+export type { KptTabIconColor, KptTabProps, KptTabsProps } from './tabs/tabs.tsx';
 export { KptAccordion, KptAccordionPanel } from './accordion/accordion.tsx';
 export type { KptAccordionPanelProps, KptAccordionProps } from './accordion/accordion.tsx';
 export { KptPanel, KptPanelActions } from './panel/panel.tsx';
@@ -74,7 +74,7 @@ export { KptDataTable } from './data-table/data-table.tsx';
 export type { KptDataTableProps } from './data-table/data-table.tsx';
 export { exportTableCsv } from './data-table/export-csv.ts';
 export type { KptCellEditContext, KptCellEditEvent, KptCellEditRenderers, KptCellRenderers, KptColumn, KptColumnEdit, KptColumnEditType, KptSortDir, KptTableLazyState, } from './data-table/data-table-types.ts';
-export type { KptColumnFilter, KptColumnFilterType, KptColumnSummary, KptSummaryFn } from '@konce-pt/table';
+export type { KptColumnFilter, KptColumnFilterType, KptColumnGroup, KptColumnSummary, KptSummaryFn } from '@konce-pt/table';
 export { KptDataView } from './data-view/data-view.tsx';
 export type { KptDataViewLayout, KptDataViewProps } from './data-view/data-view.tsx';
 export { KptTree } from './tree/tree.tsx';
@@ -123,7 +123,7 @@ export type { KptOverlayProps } from './internal/overlay.tsx';
 export { KptButtonGroup } from './button-group/button-group.tsx';
 export type { KptButtonGroupProps } from './button-group/button-group.tsx';
 export { KptSelect } from './select/select.tsx';
-export type { KptSelectProps } from './select/select.tsx';
+export type { KptSelectMultipleProps, KptSelectProps, KptSelectSingleProps } from './select/select.tsx';
 export type { KptAlertVariant, KptNavigateEvent, KptOption } from './shared/types.ts';
 export { KptFormField } from './form-field/form-field.tsx';
 export type { KptFormFieldLabelType, KptFormFieldProps } from './form-field/form-field.tsx';
@@ -194,6 +194,8 @@ export type { KptCardHeadingLevel, KptCardProps, KptCardVariant } from './card/c
 export { KptI18nProvider, useKptI18n, useKptMessages } from './i18n/i18n-context.tsx';
 export type { KptI18nContextValue, KptI18nOverrides, KptI18nProviderProps } from './i18n/i18n-context.tsx';
 export { KPT_MESSAGES_EN, KPT_MESSAGES_PL } from '@konce-pt/i18n';
+export { KptMotionProvider, useKptMotion } from './motion/motion-context.tsx';
+export type { KptMotionProviderProps, KptMotionConfig, KptLayoutMotion } from './motion/motion-context.tsx';
 export type { DeepPartial, KptLocale, KptMessages } from '@konce-pt/i18n';
 export { cn } from './internal/cn.ts';
 export type { ClassValue } from './internal/cn.ts';

package/dist/public-api.js

@@ -109,6 +109,7 @@ export { KptCard, KptCardActions, KptCardFooter, KptCardHeader, KptCardLead, Kpt
 // i18n
 export { KptI18nProvider, useKptI18n, useKptMessages } from "./i18n/i18n-context.js";
 export { KPT_MESSAGES_EN, KPT_MESSAGES_PL } from '@konce-pt/i18n';
+export { KptMotionProvider, useKptMotion } from "./motion/motion-context.js";
 // Prymitywy pomocnicze
 export { cn } from "./internal/cn.js";
 export { composeRefs } from "./internal/compose-refs.js";

package/dist/select/llms.txt

@@ -15,7 +15,11 @@ A select on its own panel. Variants: single, with a search box (`filter`) and mu
 
 ## Props
 - `options`: `KptOption<T>[]` - `{ label, value, disabled? }`
-- `value` / `defaultValue` / `onValueChange` - a single `T`, or `T[]` in `multiple` mode
+- `value` / `defaultValue` / `onValueChange` - a single `T`, or `T[]` in `multiple` mode. The handler type
+  follows `multiple` (overloads): without it `(value: T) => void` - a single select cannot clear its
+  choice, so it never reports an array or `null`; with `multiple` `(value: T[]) => void`. A flag computed at
+  run time (`multiple={flag}`) keeps the wide `T | T[] | null`. Types: `KptSelectSingleProps`,
+  `KptSelectMultipleProps`, `KptSelectProps` (the wide one)
 - `open` / `defaultOpen` / `onOpenChange` - the panel state, so the list can be opened from outside
 - `placeholder`, `multiple`, `filter`, `disabled`, `invalid`, `touched`
 - `onTouch()` - fires when the panel closes or focus leaves the closed trigger

package/dist/select/select.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentPropsWithRef } from 'react';
+import { type ComponentPropsWithRef, type JSX } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptOption } from '../shared/types.ts';
 export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'onChange' | 'defaultValue'>, KptI18nOverrides {
@@ -28,6 +28,23 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
     /** Wywoływane, gdy panel się zamyka albo trigger traci fokus. */
     onTouch?: () => void;
 }
+/**
+ * Pojedynczy wybór: `onValueChange` dostaje zawsze wybraną opcję - nigdy tablicę ani `null`, bo
+ * lista bez `multiple` nie ma jak wyczyścić wyboru. Rodzic trzyma więc zwykłe `T`.
+ */
+export interface KptSelectSingleProps<T> extends Omit<KptSelectProps<T>, 'multiple' | 'value' | 'defaultValue' | 'onValueChange'> {
+    multiple?: false;
+    value?: T | null;
+    defaultValue?: T | null;
+    onValueChange?: (value: T) => void;
+}
+/** Wybór wielokrotny: wartością jest zawsze tablica (pusta, gdy nic nie wybrano). */
+export interface KptSelectMultipleProps<T> extends Omit<KptSelectProps<T>, 'multiple' | 'value' | 'defaultValue' | 'onValueChange'> {
+    multiple: true;
+    value?: T[] | null;
+    defaultValue?: T[] | null;
+    onValueChange?: (value: T[]) => void;
+}
 /**
  * Lista wyboru (select) na własnym panelu. Warianty: pojedynczy, z wyszukiwarką (`filter`)
  * i wielokrotny (`multiple`, chipy).
@@ -46,5 +63,10 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
  * @example
  * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz..." />
  * <KptSelect options={tags} multiple filter value={tags} onValueChange={setTags} />
+ *
+ * Typ `onValueChange` idzie za `multiple`: bez niego `(value: T)`, z `multiple` - `(value: T[])`.
+ * `multiple` liczone w locie (`multiple={flag}`) zostawia szeroki typ `T | T[] | null`.
  */
-export declare function KptSelect<T>({ options, placeholder, multiple, filter, disabled, readOnly, invalid, touched, value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptSelectProps<T>>): import("react").JSX.Element;
+export declare function KptSelect<T>(props: Readonly<KptSelectSingleProps<T>>): JSX.Element;
+export declare function KptSelect<T>(props: Readonly<KptSelectMultipleProps<T>>): JSX.Element;
+export declare function KptSelect<T>(props: Readonly<KptSelectProps<T>>): JSX.Element;

package/dist/select/select.js

@@ -18,25 +18,6 @@ function filterSelectOptions(options, text) {
     const q = foldMentionText(text.trim());
     return q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
 }
-/**
- * Lista wyboru (select) na własnym panelu. Warianty: pojedynczy, z wyszukiwarką (`filter`)
- * i wielokrotny (`multiple`, chipy).
- *
- * Klawiatura według wzorca WAI-ARIA "select-only combobox": fokus zostaje na polu, a aktywna opcja
- * idzie przez `aria-activedescendant`. `ArrowDown`/`ArrowUp`/`Enter`/`Spacja` otwierają listę na wybranej opcji,
- * strzałki, `Home`/`End`, `PageUp`/`PageDown` chodzą po opcjach (z pominięciem wyłączonych),
- * wpisywane litery skaczą do pasującej opcji (bez polskich znaków), `Enter` wybiera, `Escape`
- * zamyka. Z `filter` fokus przechodzi do pola wyszukiwania, które obsługuje te same klawisze.
- * W trybie `multiple` `Backspace` na zamkniętym polu usuwa ostatni wybór.
- *
- * Wewnątrz `KptFormField` zgłasza wypełnienie hookiem `useKptFormFieldFilled`, więc etykieta
- * Float Label unosi się nad wybraną wartością - natywnego pola, z którego wrapper mógłby to
- * odczytać, tu nie ma.
- *
- * @example
- * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz..." />
- * <KptSelect options={tags} multiple filter value={tags} onValueChange={setTags} />
- */
 export function KptSelect({ options = [], placeholder = '', multiple = false, filter = false, disabled = false, readOnly = false, invalid = false, touched, value, defaultValue = null, onValueChange, open, defaultOpen = false, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required = false, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }) {
     /** `div` z rolą nie dostaje nazwy z `label[for]` - stąd `aria-labelledby` na etykietę wrappera. */
     const field = useKptFieldA11y(id, 'kpt-select-trigger');