@konce-pt/react 0.11.2 → 0.14.0

package/dist/file-upload/file-upload.js

@@ -1,11 +1,13 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
 const EMPTY = [];
-/** Rozmiar pliku w KB albo MB — bez bibliotek, bo to jedna reguła. */
+/** Rozmiar pliku w KB albo MB - bez bibliotek, bo to jedna reguła. */
 function formatSize(file) {
     const kb = file.size / 1024;
     return kb < 1024 ? `${kb.toFixed(0)} KB` : `${(kb / 1024).toFixed(1)} MB`;
@@ -19,24 +21,30 @@ function fileIcon(file) {
  * Wartością jest tablica `File`.
  *
  * Strefa to `role="button"` z jednym przystankiem Tab: `Enter` i spacja otwierają okno wyboru,
- * tak jak kliknięcie — natywne pole pliku jest ukryte, więc bez tego klawiatura nie miałaby
+ * tak jak kliknięcie - natywne pole pliku jest ukryte, więc bez tego klawiatura nie miałaby
  * jak wybrać pliku. `disabled` wyjmuje strefę z kolejności Tab. Stan błędu: `invalid`
  * i `touched` (pominięty `touched` = błąd widać od razu, jak w `KptInput`).
  *
  * @example
  * <KptFileUpload value={files} onValueChange={setFiles} accept="image/*" multiple />
  */
-export function KptFileUpload({ value, defaultValue = EMPTY, onValueChange, accept = '', multiple = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptFileUpload({ value, defaultValue = EMPTY, onValueChange, accept = '', multiple = false, disabled = false, readOnly = false, id, ariaLabel = null, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const inputRef = useRef(null);
+    const zoneRef = useRef(null);
+    /** `div` z rolą nie dostaje nazwy z `label[for]` - stąd `aria-labelledby` na etykietę wrappera. */
+    const field = useKptFieldA11y(id, 'kpt-file-upload');
+    // Podpowiedź rozcięta w miejscu `{action}` - pogrubienie robi JSX, nie HTML ze słownika.
+    const [hintBefore = '', hintAfter = ''] = t('fileUpload.hint').split('{action}');
+    const locked = disabled || readOnly;
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const [dragover, setDragover] = useState(false);
     const showError = invalid && (touched ?? true);
     const openPicker = () => {
-        if (!disabled)
+        if (!locked)
             inputRef.current?.click();
     };
-    /** `Enter` / spacja na strefie — spacja bez `preventDefault` przewinęłaby stronę. */
+    /** `Enter` / spacja na strefie - spacja bez `preventDefault` przewinęłaby stronę. */
     const onZoneKeyDown = (event) => {
         if (event.key !== 'Enter' && event.key !== ' ')
             return;
@@ -52,20 +60,23 @@ export function KptFileUpload({ value, defaultValue = EMPTY, onValueChange, acce
     };
     const onSelect = (event) => {
         addFiles(event.target.files);
-        // Czyszczenie pola pozwala wybrać ten sam plik drugi raz — inaczej `change` by nie poleciał.
+        // Czyszczenie pola pozwala wybrać ten sam plik drugi raz - inaczej `change` by nie poleciał.
         event.target.value = '';
     };
-    return (_jsxs("div", { className: cn('kpt-file-upload-host', className), ...rest, children: [_jsxs("div", { className: cn('kpt-file-upload__zone', dragover && 'is-dragover', disabled && 'is-disabled'), role: "button", tabIndex: disabled ? -1 : 0, "aria-disabled": disabled || undefined, "aria-invalid": showError || undefined, "data-invalid": showError ? '' : undefined, onClick: openPicker, onKeyDown: onZoneKeyDown, onDragOver: (event) => {
+    return (_jsxs("div", { className: cn('kpt-file-upload-host', className), ...rest, children: [_jsxs("div", { className: cn('kpt-file-upload__zone', dragover && 'is-dragover', disabled && 'is-disabled'), ref: zoneRef, role: "button", id: field.id, tabIndex: disabled ? -1 : 0, "aria-disabled": locked || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, "data-invalid": showError ? '' : undefined, onClick: openPicker, onKeyDown: onZoneKeyDown, onDragOver: (event) => {
                     event.preventDefault();
-                    if (!disabled)
+                    if (!locked)
                         setDragover(true);
                 }, onDragLeave: () => setDragover(false), onDrop: (event) => {
                     event.preventDefault();
                     setDragover(false);
-                    if (!disabled)
+                    if (!locked)
                         addFiles(event.dataTransfer?.files);
-                }, children: [_jsx("input", { ref: inputRef, type: "file", hidden: true, accept: accept, multiple: multiple, onChange: onSelect }), _jsx(KptIcon, { name: "upload", className: "kpt-file-upload__icon" }), _jsx("div", { className: "kpt-file-upload__text", dangerouslySetInnerHTML: { __html: t('fileUpload.hint') } }), accept ? _jsx("div", { className: "kpt-file-upload__hint", children: accept }) : null] }), current.length ? (_jsx("ul", { className: "kpt-file-upload__list", children: current.map((file, index) => (_jsxs("li", { className: "kpt-file-upload__file", children: [_jsx(KptIcon, { name: fileIcon(file) }), _jsx("span", { className: "kpt-file-upload__name", children: file.name }), _jsx("span", { className: "kpt-file-upload__size", children: formatSize(file) }), _jsx("button", { type: "button", className: "kpt-file-upload__remove", "aria-label": t('fileUpload.remove'), onClick: (event) => {
+                }, children: [_jsx("input", { ref: inputRef, type: "file", hidden: true, accept: accept, multiple: multiple, onChange: onSelect }), _jsx(KptIcon, { name: "upload", className: "kpt-file-upload__icon" }), _jsxs("div", { className: "kpt-file-upload__text", children: [hintBefore, _jsx("strong", { children: t('fileUpload.hintAction') }), hintAfter] }), accept ? _jsx("div", { className: "kpt-file-upload__hint", children: accept }) : null] }), current.length ? (_jsx("ul", { className: "kpt-file-upload__list", children: current.map((file, index) => (_jsxs("li", { className: "kpt-file-upload__file", children: [_jsx(KptIcon, { name: fileIcon(file) }), _jsx("span", { className: "kpt-file-upload__name", children: file.name }), _jsx("span", { className: "kpt-file-upload__size", children: formatSize(file) }), readOnly ? null : (_jsx("button", { type: "button", className: "kpt-file-upload__remove", "aria-label": `${t('fileUpload.remove')}: ${file.name}`, onClick: (event) => {
                                 event.stopPropagation();
                                 setCurrent(current.filter((item) => item !== file));
-                            }, children: _jsx(KptIcon, { name: "trash" }) })] }, `${index}-${file.name}`))) })) : null] }));
+                                onTouch?.();
+                                // Przycisk znika razem z pozycją - fokus wraca na strefę, a nie spada na <body>.
+                                zoneRef.current?.focus();
+                            }, children: _jsx(KptIcon, { name: "trash" }) }))] }, `${index}-${file.name}`))) })) : null] }));
 }

package/dist/file-upload/llms.txt

@@ -8,19 +8,19 @@ Import: `import { KptFileUpload } from '@konce-pt/react';`
     <div class="kpt-file-upload-host">
       <div class="kpt-file-upload__zone is-dragover" role="button" tabindex="0">
         <input type="file" hidden>
-        <span class="kpt-icon-host kpt-file-upload__icon">…</span>
+        <span class="kpt-icon-host kpt-file-upload__icon">...</span>
         <div class="kpt-file-upload__text"><strong>Click</strong> or drag files here</div>
         <div class="kpt-file-upload__hint">image/*</div>
       </div>
       <ul class="kpt-file-upload__list">
-        <li class="kpt-file-upload__file">…name, size, remove…</li>
+        <li class="kpt-file-upload__file">...name, size, remove...</li>
       </ul>
     </div>
 
 ## Props
-- `value` / `defaultValue` / `onValueChange` — the `File[]`
-- `accept`: string (e.g. `'image/*'`) — the native picker filter, also shown under the zone
-- `multiple`: boolean — off, only the first file is kept
+- `value` / `defaultValue` / `onValueChange` - the `File[]`
+- `accept`: string (e.g. `'image/*'`) - the native picker filter, also shown under the zone
+- `multiple`: boolean - off, only the first file is kept
 - `disabled`, `invalid`, `touched`, `onTouch()`
 - `className`, `ref` and every other `<div>` prop go to the host
 
@@ -28,9 +28,9 @@ Import: `import { KptFileUpload } from '@konce-pt/react';`
 `event.target.value = ''` after reading the files, otherwise picking the same file twice in a row
 would fire no `change` and the second pick would be silently lost.
 
-## The hint carries markup
-`fileUpload.hint` holds a `<strong>`, so it is rendered with `dangerouslySetInnerHTML` — the text
-comes from the dictionary (ours or the app's), never from user input.
+## The hint is plain text
+`fileUpload.hint` holds an `{action}` placeholder that is replaced by `fileUpload.hintAction` in
+`<strong>`. Dictionaries carry no HTML, so a translation from a CMS cannot inject markup.
 
 ## Examples
     <KptFileUpload value={files} onValueChange={setFiles} accept="image/*" multiple />
@@ -56,4 +56,7 @@ focus ring `--kpt-color-focus-ring`.
 
 ## Accessibility
 The remove button is labelled from the dictionary. The zone itself is the keyboard path to the
-system picker — see "Keyboard and states" above.
+system picker - see "Keyboard and states" above.
+
+## Read-only and required
+`readOnly` shows the list without the remove buttons and does not open the picker nor accept a drop. The zone takes `id` and `ariaLabel` and is linked to `kpt-form-field` (label and description); `button` accepts neither `aria-invalid` nor `aria-required`, so the error is the linked message. The hint is plain text: `fileUpload.hint` with `{action}` and `fileUpload.hintAction` (bold) - dictionaries no longer carry HTML. The remove button names the file.

package/dist/form-field/form-field-context.d.ts

@@ -6,13 +6,13 @@
  * zbudowany na liście) zgłaszają je przez `useKptFormFieldFilled`.
  */
 export interface KptFormFieldContextValue {
-    /** Id, którym wrapper wiąże `label[for]` — kontrolka bez własnego `id` nadaje je swojemu elementowi. */
+    /** Id, którym wrapper wiąże `label[for]` - kontrolka bez własnego `id` nadaje je swojemu elementowi. */
     controlId: string;
     /** Id elementu etykiety albo `undefined`, gdy wrapper jej nie pokazuje. */
     labelId: string | undefined;
     /** Id widocznego komunikatu (błąd albo podpowiedź) albo `undefined`. */
     describedBy: string | undefined;
-    /** Kontrolka z własnym `id` zgłasza je wrapperowi — na nie wskaże `label[for]`. */
+    /** Kontrolka z własnym `id` zgłasza je wrapperowi - na nie wskaże `label[for]`. */
     reportControlId: (id: string | null) => void;
     /** Czy pole jest oznaczone jako nieprawidłowe (niepusty `error` na wrapperze). */
     invalid: boolean;
@@ -32,11 +32,11 @@ export interface KptFieldA11y {
     /** Id elementu fokusowalnego: własne `id`, potem `controlId` wrappera, potem wygenerowane. */
     id: string;
     /**
-     * Id etykiety wrappera — dla kontrolek na elemencie, którego `label[for]` nie nazywa
+     * Id etykiety wrappera - dla kontrolek na elemencie, którego `label[for]` nie nazywa
      * (`div` z rolą, `contenteditable`). Natywne `input`/`textarea` nazywa już samo `htmlFor`.
      */
     labelledBy: string | undefined;
-    /** Id podpowiedzi albo błędu wrappera — do `aria-describedby`. */
+    /** Id podpowiedzi albo błędu wrappera - do `aria-describedby`. */
     describedBy: string | undefined;
 }
 /**

package/dist/form-field/form-field.d.ts

@@ -1,6 +1,7 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type KptEnterMotion } from '@konce-pt/motion';
 /**
- * Wariant etykiety: `fixed` (statyczna nad kontrolką) albo Float Label — `over`
+ * Wariant etykiety: `fixed` (statyczna nad kontrolką) albo Float Label - `over`
  * (nad obramowaniem), `in` (u góry wewnątrz pola), `on` (na obramowaniu, notch).
  */
 export type KptFormFieldLabelType = 'fixed' | 'over' | 'in' | 'on';
@@ -9,7 +10,7 @@ export interface KptFormFieldProps extends Omit<ComponentPropsWithRef<'div'>, 'c
     label?: string;
     /** Podpowiedź pod kontrolką (ukrywana, gdy jest błąd). */
     hint?: string;
-    /** Komunikat błędu — gdy niepusty, pole jest oznaczone jako nieprawidłowe. */
+    /** Komunikat błędu - gdy niepusty, pole jest oznaczone jako nieprawidłowe. */
     error?: string | null;
     /** Oznacz pole jako wymagane (gwiazdka przy etykiecie). */
     required?: boolean;
@@ -20,11 +21,18 @@ export interface KptFormFieldProps extends Omit<ComponentPropsWithRef<'div'>, 'c
     controlId?: string;
     /** Wariant etykiety; uniesienie następuje przy focusie lub wypełnieniu pola. */
     labelType?: KptFormFieldLabelType;
+    /**
+     * Ruch: `spring` - komunikat wjeżdża z rozmycia, pole potrząsa się, gdy staje się błędne, etykieta
+     * float unosi się na sprężynie; `fade` - komunikat się przenika; `none` - bez ruchu. Bez wartości
+     * bierze `enter` z `KptMotionProvider` (domyślnie `spring`); `enabled={false}` i systemowe
+     * "ogranicz ruch" wyłączają go zawsze.
+     */
+    enterMotion?: KptEnterMotion;
     children?: ReactNode;
 }
 /**
  * Wrapper pola formularza: etykieta, podpowiedź i komunikat błędu wokół dowolnej kontrolki.
- * Prezentacyjny — stan błędu przekazuje się przez `error`.
+ * Prezentacyjny - stan błędu przekazuje się przez `error`.
  *
  * Wypełnienie (sterujące uniesieniem etykiety) wrapper odczytuje z natywnego `input`/`textarea`
  * w środku, po zdarzeniach `input`/`change` oraz z wartości początkowej. Działa więc tak samo
@@ -36,4 +44,4 @@ export interface KptFormFieldProps extends Omit<ComponentPropsWithRef<'div'>, 'c
  *   <KptInput type="email" name="email" />
  * </KptFormField>
  */
-export declare function KptFormField({ label, hint, error, required, controlId, labelType, className, children, ref, ...rest }: Readonly<KptFormFieldProps>): import("react").JSX.Element;
+export declare function KptFormField({ label, hint, error, required, controlId, labelType, enterMotion, className, children, ref, ...rest }: Readonly<KptFormFieldProps>): import("react").JSX.Element;

package/dist/form-field/form-field.js

@@ -1,12 +1,15 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { cn } from "../internal/cn.js";
 import { composeRefs } from "../internal/compose-refs.js";
 import { useKptId } from "../internal/use-id.js";
 import { KptFormFieldContext } from "./form-field-context.js";
+import { playShakeMotion, resolveEnterMotion } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
 /**
  * Wrapper pola formularza: etykieta, podpowiedź i komunikat błędu wokół dowolnej kontrolki.
- * Prezentacyjny — stan błędu przekazuje się przez `error`.
+ * Prezentacyjny - stan błędu przekazuje się przez `error`.
  *
  * Wypełnienie (sterujące uniesieniem etykiety) wrapper odczytuje z natywnego `input`/`textarea`
  * w środku, po zdarzeniach `input`/`change` oraz z wartości początkowej. Działa więc tak samo
@@ -18,14 +21,32 @@ import { KptFormFieldContext } from "./form-field-context.js";
  *   <KptInput type="email" name="email" />
  * </KptFormField>
  */
-export function KptFormField({ label = '', hint = '', error = null, required = false, controlId = '', labelType = 'fixed', className, children, ref, ...rest }) {
+export function KptFormField({ label = '', hint = '', error = null, required = false, controlId = '', labelType = 'fixed', enterMotion, className, children, ref, ...rest }) {
     const hostRef = useRef(null);
+    const motion = resolveEnterMotion(enterMotion, useKptMotion());
+    const rootRef = useRef(null);
+    const controlRef = useRef(null);
+    const wasInvalid = useRef(null);
+    // Wejścia komunikatów dopiero po pierwszym renderze - błędy obecne od startu stoją. Atrybut idzie
+    // wprost na element: React nim nie zarządza, więc go nie nadpisze (klasę nadpisałby przy zmianie `error`).
+    useEffect(() => {
+        if (rootRef.current)
+            rootRef.current.dataset['live'] = '';
+    }, []);
+    // Potrząśnięcie tylko przy przejściu "poprawne -> błędne", nie przy każdej zmianie treści błędu.
+    const invalid = !!error;
+    useEffect(() => {
+        const before = wasInvalid.current;
+        wasInvalid.current = invalid;
+        if (before === false && invalid && motion === 'spring' && controlRef.current)
+            playShakeMotion(controlRef.current);
+    }, [invalid, motion]);
     const [nativeFilled, setNativeFilled] = useState(false);
     const [reportedFilled, setReportedFilled] = useState(null);
     const generatedId = useKptId(undefined, 'kpt-form-field-control');
     const baseId = useKptId(undefined, 'kpt-form-field');
     const id = controlId || generatedId;
-    // Kontrolka z własnym `id` zgłasza je przez kontekst — wtedy `label[for]` wskazuje właśnie je.
+    // Kontrolka z własnym `id` zgłasza je przez kontekst - wtedy `label[for]` wskazuje właśnie je.
     const [reportedId, setReportedId] = useState(null);
     const labelFor = controlId || reportedId || generatedId;
     const labelId = label ? `${baseId}-label` : undefined;
@@ -36,11 +57,11 @@ export function KptFormField({ label = '', hint = '', error = null, required = f
         const el = hostRef.current?.querySelector('.kpt-form-field__control input, .kpt-form-field__control textarea');
         setNativeFilled(!!el && el.value !== '');
     }, []);
-    // Wartość początkowa (np. pole prefill) — po pierwszym renderze projekcji, przed malowaniem,
+    // Wartość początkowa (np. pole prefill) - po pierwszym renderze projekcji, przed malowaniem,
     // żeby uniesiona etykieta nie przeskoczyła na oczach użytkownika.
     useLayoutEffect(updateFilled, [updateFilled]);
     // Kontrolowana wartość zmieniana z zewnątrz nie emituje zdarzenia `input`, więc odczyt
-    // powtarzamy po każdym renderze — to jeden `querySelector`, nie warto tu optymalizować.
+    // powtarzamy po każdym renderze - to jeden `querySelector`, nie warto tu optymalizować.
     useEffect(updateFilled);
     const filled = reportedFilled ?? nativeFilled;
     const context = useMemo(() => ({
@@ -51,5 +72,5 @@ export function KptFormField({ label = '', hint = '', error = null, required = f
         reportFilled: setReportedFilled,
         reportControlId: setReportedId,
     }), [id, labelId, describedBy, error]);
-    return (_jsx(KptFormFieldContext.Provider, { value: context, children: _jsx("div", { className: cn('kpt-form-field-host', className), ref: composeRefs(hostRef, ref), onInput: updateFilled, onChange: updateFilled, ...rest, children: _jsxs("div", { className: cn('kpt-form-field', `kpt-form-field--${labelType}`, labelType !== 'fixed' && 'kpt-form-field--float', error && 'kpt-form-field--invalid'), children: [_jsxs("div", { className: cn('kpt-form-field__box', filled && 'is-filled'), children: [label ? (_jsxs("label", { className: "kpt-form-field__label", id: labelId, htmlFor: labelFor, children: [label, required ? (_jsx("span", { className: "kpt-form-field__required", "aria-hidden": "true", children: "*" })) : null] })) : null, _jsx("div", { className: "kpt-form-field__control", children: children })] }), error ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--error", role: "alert", id: messageId, children: error })) : hint ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--hint", id: messageId, children: hint })) : null] }) }) }));
+    return (_jsx(KptFormFieldContext.Provider, { value: context, children: _jsx("div", { className: cn('kpt-form-field-host', className), ref: composeRefs(hostRef, ref), onInput: updateFilled, onChange: updateFilled, ...rest, children: _jsxs("div", { ref: rootRef, "data-motion": motion, className: cn('kpt-form-field', `kpt-form-field--${labelType}`, labelType !== 'fixed' && 'kpt-form-field--float', error && 'kpt-form-field--invalid'), children: [_jsxs("div", { className: cn('kpt-form-field__box', filled && 'is-filled'), children: [label ? (_jsxs("label", { className: "kpt-form-field__label", id: labelId, htmlFor: labelFor, children: [label, required ? (_jsx("span", { className: "kpt-form-field__required", "aria-hidden": "true", children: "*" })) : null] })) : null, _jsx("div", { ref: controlRef, className: "kpt-form-field__control", children: children })] }), error ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--error", role: "alert", id: messageId, children: error }, error)) : hint ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--hint", id: messageId, children: hint })) : null] }) }) }));
 }

package/dist/form-field/llms.txt

@@ -7,30 +7,31 @@ Import: `import { KptFormField } from '@konce-pt/react';`
     <div class="kpt-form-field-host">
       <div class="kpt-form-field kpt-form-field--fixed">
         <div class="kpt-form-field__box is-filled">
-          <label class="kpt-form-field__label" for="…">E-mail<span class="kpt-form-field__required">*</span></label>
-          <div class="kpt-form-field__control">…control…</div>
+          <label class="kpt-form-field__label" for="...">E-mail<span class="kpt-form-field__required">*</span></label>
+          <div class="kpt-form-field__control">...control...</div>
         </div>
         <p class="kpt-form-field__message kpt-form-field__message--hint">Company e-mail</p>
       </div>
     </div>
 
 ## Props
-- `label`: string — the label text
-- `hint`: string — a hint under the control, hidden while there is an error
-- `error`: string | null — when non-empty the field is marked invalid
-- `required`: boolean — an asterisk next to the label
-- `controlId`: string — empty means the wrapper generates one and hands it to the control
+- `label`: string - the label text
+- `hint`: string - a hint under the control, hidden while there is an error
+- `error`: string | null - when non-empty the field is marked invalid
+- `required`: boolean - an asterisk next to the label
+- `controlId`: string - empty means the wrapper generates one and hands it to the control
 - `labelType`: 'fixed' | 'over' | 'in' | 'on' (default 'fixed')
+- `enterMotion`: 'spring' | 'fade' | 'none' - how the message and the error appear (default from `KptMotionProvider`, else `spring`)
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Label wiring
 The wrapper generates a control id and publishes it through context, so `<KptInput>` inside needs
-no configuration — `label[for]` and `input[id]` always match. Pass `controlId` to take over; a control
+no configuration - `label[for]` and `input[id]` always match. Pass `controlId` to take over; a control
 with its own `id` reports it, and the label follows.
 
 The context also carries the label's id and the id of the visible hint or error. Every library
 control uses them through `useKptFieldA11y`: the hint or error lands in `aria-describedby`, and a
-control on a `div` with a role (`KptSelect`, `KptDatepicker`, `KptRadioGroup`, `KptRichText`…) gets
+control on a `div` with a role (`KptSelect`, `KptDatepicker`, `KptRadioGroup`, `KptRichText`...) gets
 `aria-labelledby` pointing at the label, because `label[for]` does not name it. A custom control:
 
     const field = useKptFieldA11y(id, 'my-control');
@@ -39,7 +40,7 @@ control on a `div` with a role (`KptSelect`, `KptDatepicker`, `KptRadioGroup`, `
 ## Float labels
 `labelType` other than `fixed` turns on the floating label with an animated transition: `over`
 (above the border), `in` (top inside the field), `on` (on the border, notch). The label floats on
-focus (CSS `:focus-within`) or when the field is filled — no placeholder required.
+focus (CSS `:focus-within`) or when the field is filled - no placeholder required.
 
 Filled state is read from the projected `input`/`textarea` on `input`/`change` and from the initial
 value, so it works for controlled and uncontrolled fields alike. A control with no native field
@@ -54,11 +55,24 @@ reports it with `useKptFormFieldFilled(filled)`.
       <KptInput value={over} onValueChange={setOver} />
     </KptFormField>
 
+## Motion
+`enterMotion` (`spring | fade | none`):
+- the message under the field enters on every change - hint -> error, error A -> error B - sliding in
+  from above and sharpening out of a blur (`fade`: only fades); each new error is a new element, so it
+  is also announced again;
+- `spring` only: the control shakes briefly when the field turns invalid - not when the error text
+  changes and not for an error present on load; the floating label rises on a spring.
+
+Messages present on the first render do not animate. With no value it takes `enter` from `KptMotionProvider`
+(default `spring`); `enabled: false` and the system "reduce motion" setting always win. Every form
+control's surface (border, focus ring, background) changes smoothly on hover, focus and error - a shared
+rule, independent of this input.
+
 ## Tokens
 `--kpt-form-field-{label,hint,error,border,border-focus,border-error,radius}` and
 `--kpt-color-danger` for the required asterisk.
 
 ## Accessibility
 The error message carries `role="alert"`, so a screen reader announces it as it appears. The
-asterisk is `aria-hidden` — the required state belongs on the control (`aria-required`), not on
+asterisk is `aria-hidden` - the required state belongs on the control (`aria-required`), not on
 decoration.

package/dist/galleria/galleria.d.ts

@@ -14,12 +14,12 @@ export interface KptGalleriaProps extends Omit<ComponentPropsWithRef<'div'>, 'on
     showThumbnails?: boolean;
 }
 /**
- * Galleria — duży podgląd obrazu z paskiem miniatur i nawigacją.
+ * Galleria - duży podgląd obrazu z paskiem miniatur i nawigacją.
  *
  * Klawiatura: na całej galerii strzałki w lewo/prawo przechodzą do sąsiedniego obrazu (w RTL
- * odwrotnie), `Home`/`End` — do pierwszego/ostatniego; gdy fokus stoi na miniaturze, idzie za
+ * odwrotnie), `Home`/`End` - do pierwszego/ostatniego; gdy fokus stoi na miniaturze, idzie za
  * 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.
+ * ogłaszana uprzejmie ("Obraz 2 z 4: ...") - dopiero po działaniu użytkownika, nie przy starcie.
  *
  * @example
  * <KptGalleria items={photos} activeIndex={index} onActiveIndexChange={setIndex} />

package/dist/galleria/galleria.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
@@ -7,24 +8,26 @@ import { KptIcon } from "../icon/icon.js";
 /** Klawisze przechodzące między obrazami: kierunek względem bieżącego albo skrajny indeks. */
 const NAV_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'Home', 'End']);
 /**
- * Galleria — duży podgląd obrazu z paskiem miniatur i nawigacją.
+ * Galleria - duży podgląd obrazu z paskiem miniatur i nawigacją.
  *
  * Klawiatura: na całej galerii strzałki w lewo/prawo przechodzą do sąsiedniego obrazu (w RTL
- * odwrotnie), `Home`/`End` — do pierwszego/ostatniego; gdy fokus stoi na miniaturze, idzie za
+ * odwrotnie), `Home`/`End` - do pierwszego/ostatniego; gdy fokus stoi na miniaturze, idzie za
  * 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.
+ * ogłaszana uprzejmie ("Obraz 2 z 4: ...") - dopiero po działaniu użytkownika, nie przy starcie.
  *
  * @example
  * <KptGalleria items={photos} activeIndex={index} onActiveIndexChange={setIndex} />
  */
 export function KptGalleria({ items = [], activeIndex, defaultActiveIndex = 0, onActiveIndexChange, showThumbnails = true, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
-    const [active, setActive] = useControllableState({
+    const [requested, setActive] = useControllableState({
         value: activeIndex,
         defaultValue: defaultActiveIndex,
         onChange: onActiveIndexChange,
     });
-    // Ogłoszenie dopiero po działaniu użytkownika — przy starcie region ma milczeć.
+    // Indeks przycięty do listy: po skróceniu `items` (filtr) widok nie zostaje pusty.
+    const active = Math.min(Math.max(requested, 0), Math.max(items.length - 1, 0));
+    // Ogłoszenie dopiero po działaniu użytkownika - przy starcie region ma milczeć.
     const [userMoved, setUserMoved] = useState(false);
     const thumbsRef = useRef([]);
     const rootRef = useRef(null);
@@ -47,7 +50,7 @@ export function KptGalleria({ items = [], activeIndex, defaultActiveIndex = 0, o
         const target = event.key === 'Home' ? 0 : event.key === 'End' ? last : active + (rtl ? -step : step);
         const focusOnThumb = thumbsRef.current.some((thumb) => thumb === document.activeElement);
         const next = select(target);
-        // Fokus na miniaturze idzie za aktywnym obrazem — inaczej strzałka zmieniałaby obraz,
+        // Fokus na miniaturze idzie za aktywnym obrazem - inaczej strzałka zmieniałaby obraz,
         // a fokus zostawał na poprzedniej miniaturze.
         if (focusOnThumb)
             thumbsRef.current[next]?.focus();

package/dist/galleria/llms.txt

@@ -7,19 +7,19 @@ Import: `import { KptGalleria, type KptGalleriaItem } from '@konce-pt/react';`
     <div class="kpt-galleria-host">
       <div class="kpt-galleria">
         <div class="kpt-galleria__stage">
-          <button class="kpt-galleria__nav kpt-galleria__nav--prev" aria-disabled="true" aria-label="Previous">…</button>
-          <img class="kpt-galleria__image" src="…" alt="Mountain lake">
-          <button class="kpt-galleria__nav kpt-galleria__nav--next" aria-label="Next">…</button>
+          <button class="kpt-galleria__nav kpt-galleria__nav--prev" aria-disabled="true" aria-label="Previous">...</button>
+          <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>…
+          <button class="kpt-galleria__thumb is-active" aria-current="true" aria-label="Mountain lake"><img src="..." alt=""></button>...
         </div>
         <span class="kpt-galleria__live" aria-live="polite">Image 2 of 4: Pine forest</span>
       </div>
     </div>
 
 ## Props
-- `items`: `KptGalleriaItem[]` — `{ src, thumbnail?, alt? }`
+- `items`: `KptGalleriaItem[]` - `{ src, thumbnail?, alt? }`
 - `activeIndex` / `defaultActiveIndex` / `onActiveIndexChange`
 - `showThumbnails`: boolean (default true)
 - `className`, `ref` and every other `<div>` prop go to the host
@@ -48,8 +48,8 @@ The stage `--kpt-color-muted`; the active thumbnail `--kpt-color-primary`; the a
 
 ## Accessibility
 The large image carries its `alt`. Each thumbnail is a button named by the item's `alt` (or
-`galleria.image` — “Image 3” — when there is none), with `alt=""` on the thumbnail image so the
+`galleria.image` - "Image 3" - when there is none), with `alt=""` on the thumbnail image so the
 name is not read twice; the active one carries `aria-current`. The arrows use `aria-disabled` at
 the ends instead of `disabled`, so they keep the focus. A change of image is announced politely
-through a hidden live region — `galleria.position` (“Image 2 of 4”) plus the `alt` — only after the
+through a hidden live region - `galleria.position` ("Image 2 of 4") plus the `alt` - only after the
 user acts, never on first render.

package/dist/grid/col.d.ts

@@ -3,7 +3,7 @@ import type { AsChildProps } from '../internal/types.ts';
 /** Rozpiętość kolumny: liczba, `'full'` (cała szerokość) albo dowolna wartość CSS. */
 export type KptColSpan = number | string;
 export interface KptColProps extends ComponentPropsWithRef<'div'>, AsChildProps {
-    /** Rozpiętość kolumny — baza mobile-first. */
+    /** Rozpiętość kolumny - baza mobile-first. */
     span?: KptColSpan;
     /** Rozpiętość od breakpointa SM (>= 640px). */
     spanSm?: KptColSpan;
@@ -15,7 +15,7 @@ export interface KptColProps extends ComponentPropsWithRef<'div'>, AsChildProps
     spanXl?: KptColSpan;
     /** Rozpiętość od breakpointa 2XL (>= 1536px). */
     span2xl?: KptColSpan;
-    /** Numer linii, od której zaczyna się kolumna (1-based) — pozwala robić offsety. */
+    /** Numer linii, od której zaczyna się kolumna (1-based) - pozwala robić offsety. */
     start?: number | string;
     /** Kolejność wizualna (`order`). Nie zmienia kolejności w DOM ani dla czytników ekranu. */
     order?: number | string;
@@ -23,10 +23,10 @@ export interface KptColProps extends ComponentPropsWithRef<'div'>, AsChildProps
     self?: string;
 }
 /**
- * Kolumna siatki `KptGrid` — rozpiętość mobile-first z nadpisaniami per breakpoint.
+ * Kolumna siatki `KptGrid` - rozpiętość mobile-first z nadpisaniami per breakpoint.
  *
  * Wartość podana dla mniejszego breakpointa obowiązuje aż do następnego, który ją nadpisze:
- * `span={12} spanLg={5}` daje 12 na mobile, tablecie i `md`, a dopiero od `lg` — 5.
+ * `span={12} spanLg={5}` daje 12 na mobile, tablecie i `md`, a dopiero od `lg` - 5.
  *
  * Ustawia wyłącznie custom properties inline; nie dodaje ani nie usuwa klas. Z `asChild`
  * przejmuje Twój element, więc kolumną może być `<li>`, `<article>` czy komponent biblioteki.

package/dist/grid/col.js

@@ -1,9 +1,9 @@
 import { layoutStyle, renderLayout } from "./layout.js";
 /**
- * Kolumna siatki `KptGrid` — rozpiętość mobile-first z nadpisaniami per breakpoint.
+ * Kolumna siatki `KptGrid` - rozpiętość mobile-first z nadpisaniami per breakpoint.
  *
  * Wartość podana dla mniejszego breakpointa obowiązuje aż do następnego, który ją nadpisze:
- * `span={12} spanLg={5}` daje 12 na mobile, tablecie i `md`, a dopiero od `lg` — 5.
+ * `span={12} spanLg={5}` daje 12 na mobile, tablecie i `md`, a dopiero od `lg` - 5.
  *
  * Ustawia wyłącznie custom properties inline; nie dodaje ani nie usuwa klas. Z `asChild`
  * przejmuje Twój element, więc kolumną może być `<li>`, `<article>` czy komponent biblioteki.

package/dist/grid/flex.d.ts

@@ -4,7 +4,7 @@ export type KptFlexDirection = 'row' | 'row-reverse' | 'column' | 'column-revers
 export type KptFlexWrap = 'wrap' | 'nowrap' | 'wrap-reverse';
 export type KptAlignment = 'start' | 'end' | 'center' | 'stretch' | 'baseline' | 'space-between' | 'space-around' | 'space-evenly';
 export interface KptFlexProps extends ComponentPropsWithRef<'div'>, AsChildProps {
-    /** Kierunek osi głównej — baza mobile-first. */
+    /** Kierunek osi głównej - baza mobile-first. */
     direction?: KptFlexDirection;
     /** Kierunek od breakpointa MD (>= 768px). */
     directionMd?: KptFlexDirection;
@@ -26,11 +26,11 @@ export interface KptFlexProps extends ComponentPropsWithRef<'div'>, AsChildProps
     gapX?: string;
     /** Odstęp w pionie. */
     gapY?: string;
-    /** Tryb kontenerowy — zmienne dzieci reagują na szerokość tego kontenera. */
+    /** Tryb kontenerowy - zmienne dzieci reagują na szerokość tego kontenera. */
     container?: boolean;
 }
 /**
- * Kontener flexbox Koncept UI — te same zmienne i breakpointy co `KptGrid`.
+ * Kontener flexbox Koncept UI - te same zmienne i breakpointy co `KptGrid`.
  * Dla wartości bez odpowiednika w propsach (`grow`, `shrink`, `order` na dziecku)
  * używa się klas utility: `kpt-grow-1`, `kpt-order-first`, `kpt-self-end`.
  *

package/dist/grid/flex.js

@@ -1,7 +1,7 @@
 import { cn } from "../internal/cn.js";
 import { layoutStyle, renderLayout } from "./layout.js";
 /**
- * Kontener flexbox Koncept UI — te same zmienne i breakpointy co `KptGrid`.
+ * Kontener flexbox Koncept UI - te same zmienne i breakpointy co `KptGrid`.
  * Dla wartości bez odpowiednika w propsach (`grow`, `shrink`, `order` na dziecku)
  * używa się klas utility: `kpt-grow-1`, `kpt-order-first`, `kpt-self-end`.
  *

package/dist/grid/grid.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentPropsWithRef } from 'react';
 import type { AsChildProps } from '../internal/types.ts';
 export interface KptGridProps extends ComponentPropsWithRef<'div'>, AsChildProps {
-    /** Liczba kolumn — baza mobile-first. Domyślnie 12 (z CSS). */
+    /** Liczba kolumn - baza mobile-first. Domyślnie 12 (z CSS). */
     columns?: number;
     /** Liczba kolumn od breakpointa SM (>= 640px). */
     columnsSm?: number;
@@ -15,25 +15,25 @@ export interface KptGridProps extends ComponentPropsWithRef<'div'>, AsChildProps
     columns2xl?: number;
     /** Odstęp w obu osiach, np. `'1.5rem'` albo `'var(--kpt-space-6)'`. */
     gap?: string;
-    /** Odstęp między kolumnami — nadpisuje `gap` w poziomie. */
+    /** Odstęp między kolumnami - nadpisuje `gap` w poziomie. */
     gapX?: string;
-    /** Odstęp między wierszami — nadpisuje `gap` w pionie. */
+    /** Odstęp między wierszami - nadpisuje `gap` w pionie. */
     gapY?: string;
     /**
      * Tryb kontenerowy: spany dzieci reagują na szerokość TEJ siatki, nie okna.
-     * Liczba kolumn i odstępy nadal idą za viewportem — `@container` nie potrafi
+     * Liczba kolumn i odstępy nadal idą za viewportem - `@container` nie potrafi
      * odpytać elementu o jego własny kontener.
      */
     container?: boolean;
 }
 /**
- * Siatka Koncept UI — CSS Grid sterowany custom properties z `@konce-pt/grid`.
+ * Siatka Koncept UI - CSS Grid sterowany custom properties z `@konce-pt/grid`.
  *
  * Odpowiednik dyrektywy `kptGrid` z portu Angulara. Dyrektyw w Reakcie nie ma, więc siatka jest
- * komponentem — ale takim, który w trybie `asChild` niczego nie dokłada do DOM: przejmuje element,
+ * komponentem - ale takim, który w trybie `asChild` niczego nie dokłada do DOM: przejmuje element,
  * który i tak renderujesz (`<section>`, `<ul>`, `<main>`).
  *
- * Zmiana `columns` nie manipuluje klasami — ustawia zmienną inline, a układ przelicza
+ * Zmiana `columns` nie manipuluje klasami - ustawia zmienną inline, a układ przelicza
  * natywny silnik CSS.
  *
  * Wymaga arkusza `@konce-pt/grid` (`import '@konce-pt/grid';`).

package/dist/grid/grid.js

@@ -1,13 +1,13 @@
 import { cn } from "../internal/cn.js";
 import { layoutStyle, renderLayout } from "./layout.js";
 /**
- * Siatka Koncept UI — CSS Grid sterowany custom properties z `@konce-pt/grid`.
+ * Siatka Koncept UI - CSS Grid sterowany custom properties z `@konce-pt/grid`.
  *
  * Odpowiednik dyrektywy `kptGrid` z portu Angulara. Dyrektyw w Reakcie nie ma, więc siatka jest
- * komponentem — ale takim, który w trybie `asChild` niczego nie dokłada do DOM: przejmuje element,
+ * komponentem - ale takim, który w trybie `asChild` niczego nie dokłada do DOM: przejmuje element,
  * który i tak renderujesz (`<section>`, `<ul>`, `<main>`).
  *
- * Zmiana `columns` nie manipuluje klasami — ustawia zmienną inline, a układ przelicza
+ * Zmiana `columns` nie manipuluje klasami - ustawia zmienną inline, a układ przelicza
  * natywny silnik CSS.
  *
  * Wymaga arkusza `@konce-pt/grid` (`import '@konce-pt/grid';`).

package/dist/grid/layout.d.ts

@@ -10,9 +10,9 @@ export type KptLayoutValue = number | string | undefined;
  */
 export declare function layoutStyle(vars: Readonly<Record<string, KptLayoutValue>>, style: CSSProperties | undefined): CSSProperties;
 /**
- * Renderuje element układu albo — w trybie `asChild` — oddaje propsy jedynemu dziecku.
+ * Renderuje element układu albo - w trybie `asChild` - oddaje propsy jedynemu dziecku.
  *
- * To reactowy odpowiednik dyrektywy: `<KptCol asChild><li>…</li></KptCol>` nie dokłada żadnego
+ * To reactowy odpowiednik dyrektywy: `<KptCol asChild><li>...</li></KptCol>` nie dokłada żadnego
  * elementu do DOM, dokładnie jak `<li kptCol="6">` w Angularze.
  */
 export declare function renderLayout(asChild: boolean, children: ReactNode, props: Record<string, unknown>, element: 'div' | 'span'): ReactElement;