@konce-pt/react 0.11.2 → 0.14.0

package/README.md

@@ -1,11 +1,11 @@
 <div align="center">
 
-<img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — React component library" width="100%" />
+<img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI - React component library" width="100%" />
 
-# Koncept UI — React
+# Koncept UI - React
 
 **Open-source React 19 component library on the Koncept UI design system.**
-80+ components sharing the exact CSS layer with the Angular port — zero runtime dependencies.
+80+ components sharing the exact CSS layer with the Angular port - zero runtime dependencies.
 
 [![npm version](https://img.shields.io/npm/v/@konce-pt/react?color=%233b82f6&label=npm)](https://www.npmjs.com/package/@konce-pt/react)
 [![npm downloads](https://img.shields.io/npm/dm/@konce-pt/react?color=%233b82f6)](https://www.npmjs.com/package/@konce-pt/react)
@@ -24,25 +24,25 @@
 
 ## Why Koncept UI React
 
-**Koncept UI** is a free, MIT-licensed design system. This package is its **React 19** port — not a
+**Koncept UI** is a free, MIT-licensed design system. This package is its **React 19** port - not a
 lookalike, but the same rendering contract:
 
-- 🎯 **One CSS layer for both ports** — the same `kpt-*` classes, the same `--kpt-*` tokens, the same
+- **One CSS layer for both ports** - the same `kpt-*` classes, the same `--kpt-*` tokens, the same
   `@layer kpt.*` ordering. The DOM tree matches the Angular port node for node, so an app can mix
   the two and nothing shifts by a pixel.
-- 📦 **Zero runtime dependencies** — no `clsx`, no `radix`, no CSS-in-JS. `cn`, `Slot` and
+- **Zero runtime dependencies** - no `clsx`, no `radix`, no CSS-in-JS. `cn`, `Slot` and
   `composeRefs` ship with the package.
-- ⚛️ **React 19 native** — `ref` is a plain prop (no `forwardRef`), and every form control renders a
-  native `name`/`form`, so `<form action={…}>` Actions and React Hook Form's `register()` work
+- **React 19 native** - `ref` is a plain prop (no `forwardRef`), and every form control renders a
+  native `name`/`form`, so `<form action={...}>` Actions and React Hook Form's `register()` work
   **without an adapter**. Controls are usable controlled *and* uncontrolled.
-- 📊 **Flagship data table** — sorting, global and per-column filters, pagination, virtual scroll
+- **Flagship data table** - sorting, global and per-column filters, pagination, virtual scroll
   (5000+ rows), selection, column reorder & freeze, inline editing, summary row, CSV export.
-- 🎨 **100% tokenized** — every style is a `var(--kpt-*)` custom property. Light/dark theme, neutral
+- **100% tokenized** - every style is a `var(--kpt-*)` custom property. Light/dark theme, neutral
   OKLCH palette. Rebrand by swapping one token layer.
-- ♿ **Native elements first** — `<button>`, `<input>`, `<label>` wherever one exists, so keyboard and
+- **Native elements first** - `<button>`, `<input>`, `<label>` wherever one exists, so keyboard and
   screen-reader behaviour comes from the platform. Invalid state travels on `aria-invalid`, never on
   a class.
-- 🌍 **i18n built in** — English (default) & Polish out of the box, runtime locale switch, add any
+- **i18n built in** - English (default) & Polish out of the box, runtime locale switch, add any
   language with one JSON.
 
 ## Installation
@@ -52,13 +52,13 @@ npm i @konce-pt/react @konce-pt/tokens @konce-pt/styles
 # or: pnpm add / yarn add
 ```
 
-`react` and `react-dom` (`>=19`) are peers you already have. Optional extras:
+`react` and `react-dom` (`^19.2`) are peers you already have. Optional extras:
 
-- [`@konce-pt/grid`](https://www.npmjs.com/package/@konce-pt/grid) — the mobile-first layout system;
+- [`@konce-pt/grid`](https://www.npmjs.com/package/@konce-pt/grid) - the mobile-first layout system;
   its React components live in `@konce-pt/react/grid`.
-- [`@konce-pt/validators`](https://www.npmjs.com/package/@konce-pt/validators) — Polish-market
+- [`@konce-pt/validators`](https://www.npmjs.com/package/@konce-pt/validators) - Polish-market
   validators (NIP, REGON, PESEL, IBAN, postal code).
-- `leaflet` (`^1.9`) — an **optional** peer, needed only by `@konce-pt/react/map`, loaded through a
+- `leaflet` (`^1.9`) - an **optional** peer, needed only by `@konce-pt/react/map`, loaded through a
   dynamic `import()`.
 
 ## Setup
@@ -69,8 +69,8 @@ The package ships **JavaScript only**. Load the shared CSS layer once, in your a
 import '@konce-pt/tokens/css';
 import '@konce-pt/tokens/css/dark';
 import '@konce-pt/styles';            // reset, @layer ordering, theme
-import '@konce-pt/styles/components'; // the component layer — REQUIRED, this is what styles kpt-*
-import '@konce-pt/grid';              // optional — only if you use the layout classes
+import '@konce-pt/styles/components'; // the component layer - REQUIRED, this is what styles kpt-*
+import '@konce-pt/grid';              // optional - only if you use the layout classes
 ```
 
 `@konce-pt/styles/components` is generated from the same SCSS the Angular port compiles into its own
@@ -79,15 +79,18 @@ runtime; React has no other source for them, so this import is not optional.
 
 Dark theme: set `<html data-theme="dark">` (or rely on `prefers-color-scheme`).
 
+**Next.js App Router / Server Components:** every interactive component module starts with
+`'use client'`, so you can import components directly into a server component - no wrapper file.
+
 > **No CDK here.** Components with a floating panel (`KptSelect`, `KptPopover`, `KptMenu`,
-> `KptAutocomplete`, `KptDatepicker`…) portal into `document.body` through the internal
-> `KptOverlay`, so `@angular/cdk/overlay-prebuilt.css` is **not** needed — positioning lives in the
+> `KptAutocomplete`, `KptDatepicker`...) portal into `document.body` through the internal
+> `KptOverlay`, so `@angular/cdk/overlay-prebuilt.css` is **not** needed - positioning lives in the
 > component, the look in `@konce-pt/styles/components`. Inside an open `KptDialog` those panels
 > portal into the `<dialog>` instead, because `showModal()` moves it to the browser top layer.
 
 ## Quick start
 
-A login form — controlled values, the error gated on touch, no form library required:
+A login form - controlled values, the error gated on touch, no form library required:
 
 ```tsx
 import { useState } from 'react';
@@ -139,7 +142,7 @@ export function Login() {
 
 `KptFormField` generates the control id and publishes it through context, so `label[for]` and
 `input[id]` match with no configuration. Drop `value`/`onValueChange` and the field becomes
-uncontrolled — the value lives in the DOM, and a native `<form action={…}>` or React Hook Form's
+uncontrolled - the value lives in the DOM, and a native `<form action={...}>` or React Hook Form's
 `register()` picks it up as-is.
 
 Data table with sorting, filtering, pagination and a custom cell:
@@ -165,7 +168,7 @@ Data table with sorting, filtering, pagination and a custom cell:
 | --- | --- |
 | **Forms** | `KptInput`, `KptTextarea`, `KptSelect`, `KptAutocomplete`, `KptCheckbox`, `KptSwitch`, `KptSwitchGroup`, `KptRadioGroup`, `KptSlider`, `KptRating`, `KptDatepicker`, `KptDateRange`, `KptClock`, `KptColorPicker`, `KptFileUpload`, `KptInputNumber`, `KptPassword`, `KptInputOtp`, `KptChipsInput`, `KptInputMask`, `KptListbox`, `KptKnob`, `KptRichText`, `KptFormField` |
 | **Buttons & actions** | `KptButton`, `KptIconButton`, `KptButtonGroup`, `KptFab`, `KptSplitButton`, `KptSpeedDial` |
-| **Layout** | `KptAppShell`, `KptToolbar`, `KptSidenav`, `KptCard` (+ `Header`, `Footer`, `Media`, `Title`…), `KptDivider`, `KptPanel`, `KptFieldset`, `KptSplitter`, `KptScrollTop` |
+| **Layout** | `KptAppShell`, `KptToolbar`, `KptSidenav`, `KptCard` (+ `Header`, `Footer`, `Media`, `Title`...), `KptDivider`, `KptPanel`, `KptFieldset`, `KptSplitter`, `KptScrollTop` |
 | **Navigation** | `KptTabs`, `KptAccordion`, `KptBreadcrumb`, `KptStepper`, `KptMenu`, `KptMenubar`, `KptMegamenu`, `KptContextMenu` |
 | **Data** | `KptDataTable`, `KptPaginator`, `KptTree`, `KptTimeline`, `KptCarousel`, `KptDataView`, `KptPickList`, `KptOrderList`, `KptGalleria`, `KptMeterGroup` |
 | **Feedback & overlay** | `KptAlert`, `KptDialog`, `kptToast` + `KptToastContainer`, `KptTooltip`, `KptPopover`, `KptDrawer`, `KptBottomSheet`, `kptConfirm`, `KptBadge`, `KptChip`, `KptAvatar`, `KptAvatarGroup`, `KptSpinner`, `KptProgress`, `KptSkeleton`, `KptEmpty`, `KptImage`, `KptAuth` |
@@ -176,7 +179,7 @@ entry point stays small. Every component ships an `llms.txt` API sheet next to i
 
 ## Theming
 
-All visuals are driven by `var(--kpt-*)` tokens (three tiers: primitives → semantic → component).
+All visuals are driven by `var(--kpt-*)` tokens (three tiers: primitives -> semantic -> component).
 Override them in a stylesheet imported **after** `@konce-pt/styles`:
 
 ```css
@@ -189,41 +192,41 @@ Override them in a stylesheet imported **after** `@konce-pt/styles`:
 }
 ```
 
-**Common token names:** surfaces `--kpt-color-surface`, `--kpt-color-surface-sunken|raised|variant|hover|selected`; text `--kpt-color-on-surface`, `--kpt-color-on-surface-muted` (aliases `--kpt-color-text`, `--kpt-color-text-muted|subtle|inverse`); borders `--kpt-color-border`, `--kpt-color-border-strong`; accent roles in full — `{primary,danger,success,warning,info}` each with `-hover`, `-contrast`, `-subtle`, `-border`; radii `--kpt-radius-sm|md|lg|xl|full|none`; elevation `--kpt-elevation-1..4` (aliases `--kpt-shadow-sm|md|lg`). There is no `--kpt-color-bg`.
+**Common token names:** surfaces `--kpt-color-surface`, `--kpt-color-surface-sunken|raised|variant|hover|selected`; text `--kpt-color-on-surface`, `--kpt-color-on-surface-muted` (aliases `--kpt-color-text`, `--kpt-color-text-muted|subtle|inverse`); borders `--kpt-color-border`, `--kpt-color-border-strong`; accent roles in full - `{primary,danger,success,warning,info}` each with `-hover`, `-contrast`, `-subtle`, `-border`; radii `--kpt-radius-sm|md|lg|xl|full|none`; elevation `--kpt-elevation-1..4` (aliases `--kpt-shadow-sm|md|lg`). There is no `--kpt-color-bg`.
 
 Variants and sizes travel on `data-*` attributes (`data-variant`, `data-size`), never on modifier
-classes — that is what the SCSS reads.
+classes - that is what the SCSS reads.
 
 ## Icons
 
-**84 icons are built in and need no configuration** — what the components themselves draw plus the
+**84 icons are built in and need no configuration** - what the components themselves draw plus the
 staples of an application shell (`sun`, `moon`, `bell`, `settings`, `users`, `logout`,
-`layout-dashboard`, `home`, `activity`, `chart-bar`, `brand-github` …). A typical admin panel needs
+`layout-dashboard`, `home`, `activity`, `chart-bar`, `brand-github` ...). A typical admin panel needs
 nothing else.
 
 For the full **Tabler Icons** set (MIT, 5130 icons) there are two paths, and the difference is the
 bundle. Every icon is its own export, so importing by name lets the bundler keep just those:
 
 ```tsx
-// Production — two icons reach the bundle.
+// Production - two icons reach the bundle.
 import { LayoutDashboard, Rocket } from '@konce-pt/react/icons';
 import { registerKptIcons } from '@konce-pt/react';
 registerKptIcons([LayoutDashboard, Rocket]);
 
-// Prototype — every icon, about 1.2 MB.
+// Prototype - every icon, about 1.2 MB.
 import { registerKptTablerIcons } from '@konce-pt/react/icons';
 registerKptTablerIcons();
 ```
 
 `registerKptIcons` is the one that shrinks: it takes the data as an argument and imports nothing from
 the Tabler subpath. For the same reason `registerKptIcons(tabler)` with a namespace import
-(`import * as tabler`) registers everything — a namespace object handed to a function blocks static
+(`import * as tabler`) registers everything - a namespace object handed to a function blocks static
 analysis. The registry is global, so one call at the app entry is enough; no provider needed.
 
 ## Internationalization (i18n)
 
 Component labels ship in **English (default)** and **Polish**. Without a provider everything renders
-in English — a missing provider is never an error. `KptI18nProvider` sets the language for a subtree:
+in English - a missing provider is never an error. `KptI18nProvider` sets the language for a subtree:
 
 ```tsx
 import { KptI18nProvider, useKptI18n } from '@konce-pt/react';
@@ -255,7 +258,7 @@ English):
 ```tsx
 import de from './i18n/de.json';
 
-<KptI18nProvider locale="de" messages={{ de }}>…</KptI18nProvider>
+<KptI18nProvider locale="de" messages={{ de }}>...</KptI18nProvider>
 ```
 
 Any component with labels also accepts `locale` and `dictionary` props, which take priority over the
@@ -263,19 +266,52 @@ provider. Calendar weekday/month names come from the browser's `Intl` API. The c
 dictionaries live in [`@konce-pt/i18n`](https://www.npmjs.com/package/@konce-pt/i18n), shared with
 the Angular port.
 
+## Motion
+
+Components animate out of the box - springs, smooth layout changes, enter and exit - with **no provider**.
+`KptMotionProvider` sets app-wide defaults: whether motion is on at all and which kind each group of
+components gets. Every prop is optional; it writes to `<html>`, so overlays in portals follow it too.
+
+```tsx
+import { KptMotionProvider } from '@konce-pt/react';
+
+export function App() {
+  return (
+    <KptMotionProvider layout="arc" enter="fade">
+      <Routes />
+    </KptMotionProvider>
+  );
+}
+
+// <KptMotionProvider enabled={false}> - no motion at all (visual tests, kiosk)
+```
+
+| Key | Values | Components (per-component input) |
+| --- | --- | --- |
+| `enabled` | `true` \| `false` | All. `false` also zeroes CSS durations (`data-kpt-motion="off"`, `--kpt-motion-scale: 0` on `<html>`); loading indicators slow down instead of stopping |
+| `layout` | `spring` \| `arc` \| `morph` \| `none` | DataView, PickList, OrderList (`layoutMotion`) |
+| `collapse` | `spring` \| `fade` \| `none` | Accordion, Fieldset, Panel, Tree (`collapseMotion`) |
+| `enter` | `spring` \| `fade` \| `none` | Chat, ChatMessage, ChatDock, FormField (`enterMotion`); Password meter, ChipsInput and Select chips |
+| `toggle` | `spring` \| `fade` \| `none` | Checkbox, RadioGroup, Switch (`toggleMotion`); Rating stars, ButtonGroup selection |
+
+Precedence: `enabled: false` always wins, then the component's own prop, then the provider value,
+then `spring`. Small reactions (button press, field focus and error, slider handle) are plain CSS and follow
+only `enabled`. The system "reduce motion" setting is always respected. The same springs and FLIP helpers
+are available for your own views in [`@konce-pt/motion`](https://www.npmjs.com/package/@konce-pt/motion).
+
 ## Helpers
 
-- `cn(...values)` — class-name joining (the `clsx` role, no dependency).
-- `Slot` + the `asChild` prop — render as another element while keeping classes and attributes.
-- `composeRefs(...refs)` — merge several refs into one callback.
+- `cn(...values)` - class-name joining (the `clsx` role, no dependency).
+- `Slot` + the `asChild` prop - render as another element while keeping classes and attributes.
+- `composeRefs(...refs)` - merge several refs into one callback.
 
 ## Documentation
 
-- **Playground** — live demos with copyable code: [ui.konce.pt/react](https://ui.konce.pt/react).
-- **`llms.txt`** — LLM-friendly API sheets per component, shipped inside the package; the
+- **Playground** - live demos with copyable code: [ui.konce.pt/react](https://ui.konce.pt/react).
+- **`llms.txt`** - LLM-friendly API sheets per component, shipped inside the package; the
   package-wide sheet lives at [ui.konce.pt/llms/react/llms.txt](https://ui.konce.pt/llms/react/llms.txt)
   (PL mirror: [llms-pl.txt](https://ui.konce.pt/llms/react/llms-pl.txt)).
-- **Security scanners** — Socket.dev and similar tools flag i18n keys as domain names
+- **Security scanners** - Socket.dev and similar tools flag i18n keys as domain names
   (`.email`, `.today` and friends are real TLDs) and the map's default endpoints; the
   [project sheet](https://ui.konce.pt/llms.txt) explains each alert under "Security scanners".
 - Repository: [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui)
@@ -288,24 +324,24 @@ MIT © konce.pt
 
 <div align="center">
 
-## 🇵🇱 Wersja polska
+## Wersja polska
 
 </div>
 
 **Koncept UI** to darmowy system projektowy na licencji **MIT**. Ta paczka to jego port na
-**Reacta 19** — nie podobnie wyglądający zamiennik, tylko ten sam kontrakt renderowania.
+**Reacta 19** - nie podobnie wyglądający zamiennik, tylko ten sam kontrakt renderowania.
 
-- 🎯 **Jedna warstwa CSS dla obu portów** — te same klasy `kpt-*`, te same tokeny `--kpt-*`, ta sama
+- **Jedna warstwa CSS dla obu portów** - te same klasy `kpt-*`, te same tokeny `--kpt-*`, ta sama
   kolejność `@layer kpt.*`. Drzewo DOM odpowiada wersji Angulara węzeł w węzeł.
-- 📦 **Zero zależności runtime** — `cn`, `Slot` i `composeRefs` są w paczce.
-- ⚛️ **React 19** — `ref` jako zwykły prop (bez `forwardRef`), kontrolki działają kontrolowane
+- **Zero zależności runtime** - `cn`, `Slot` i `composeRefs` są w paczce.
+- **React 19** - `ref` jako zwykły prop (bez `forwardRef`), kontrolki działają kontrolowane
   i niekontrolowane, z natywnym `name`/`form` (React 19 Actions i React Hook Form bez adaptera).
-- 📊 **Flagowa tabela danych** — sortowanie, filtry globalne i kolumnowe, paginacja, virtual scroll,
+- **Flagowa tabela danych** - sortowanie, filtry globalne i kolumnowe, paginacja, virtual scroll,
   zaznaczanie, przestawianie i zamrażanie kolumn, edycja w miejscu, podsumowanie, eksport CSV.
-- 🎨 **100% na tokenach** — każdy styl to `var(--kpt-*)`. Motyw jasny/ciemny, neutralna paleta OKLCH.
-- ♿ **Natywne elementy** — `<button>`, `<input>`, `<label>` wszędzie tam, gdzie istnieją; stan błędu
+- **100% na tokenach** - każdy styl to `var(--kpt-*)`. Motyw jasny/ciemny, neutralna paleta OKLCH.
+- **Natywne elementy** - `<button>`, `<input>`, `<label>` wszędzie tam, gdzie istnieją; stan błędu
   na `aria-invalid`, nie na klasie.
-- 🌍 **Wbudowane i18n** — angielski (domyślny) i polski, przełączanie w runtime, dowolny język
+- **Wbudowane i18n** - angielski (domyślny) i polski, przełączanie w runtime, dowolny język
   jednym plikiem JSON.
 
 ### Instalacja
@@ -314,9 +350,9 @@ MIT © konce.pt
 npm i @konce-pt/react @konce-pt/tokens @konce-pt/styles
 ```
 
-`react` i `react-dom` (`>=19`) to peery, które masz już w aplikacji. Opcjonalnie:
+`react` i `react-dom` (`^19.2`) to peery, które masz już w aplikacji. Opcjonalnie:
 `@konce-pt/grid` (układ; komponenty w `@konce-pt/react/grid`), `@konce-pt/validators`
-(walidatory PL: NIP, REGON, PESEL, IBAN, kod pocztowy) oraz `leaflet` (`^1.9`) — **opcjonalny**
+(walidatory PL: NIP, REGON, PESEL, IBAN, kod pocztowy) oraz `leaflet` (`^1.9`) - **opcjonalny**
 peer, potrzebny wyłącznie dla `@konce-pt/react/map`.
 
 ### Konfiguracja
@@ -327,52 +363,55 @@ Paczka wysyła **sam JavaScript**. CSS ładujesz raz, w wejściu aplikacji:
 import '@konce-pt/tokens/css';
 import '@konce-pt/tokens/css/dark';
 import '@konce-pt/styles';            // reset, kolejność warstw, motyw
-import '@konce-pt/styles/components'; // warstwa komponentów — WYMAGANE, to ona styluje kpt-*
-import '@konce-pt/grid';              // opcjonalnie — klasy układu
+import '@konce-pt/styles/components'; // warstwa komponentów - WYMAGANE, to ona styluje kpt-*
+import '@konce-pt/grid';              // opcjonalnie - klasy układu
 ```
 
 `@konce-pt/styles/components` powstaje z tego samego SCSS-a, który port Angulara kompiluje do
-własnego bundla — stąd identyczny wygląd obu portów. Angular wstrzykuje te style w runtime, React
+własnego bundla - stąd identyczny wygląd obu portów. Angular wstrzykuje te style w runtime, React
 nie ma dla nich innego źródła, więc ten import nie jest opcjonalny.
 
 Motyw ciemny: `<html data-theme="dark">` (albo `prefers-color-scheme`). Nadpisania `--kpt-color-*`
 w arkuszu importowanym **po** `@konce-pt/styles`.
 
+**Next.js App Router / Server Components:** każdy moduł interaktywnego komponentu zaczyna się od
+`'use client'`, więc komponenty importujesz wprost do komponentu serwerowego - bez pliku-opakowania.
+
 > **CDK nie jest tu potrzebny.** Komponenty z panelem (`KptSelect`, `KptPopover`, `KptMenu`,
-> `KptAutocomplete`, `KptDatepicker`…) renderują go przez wewnętrzny `KptOverlay` do portalu na
+> `KptAutocomplete`, `KptDatepicker`...) renderują go przez wewnętrzny `KptOverlay` do portalu na
 > `document.body`, więc `@angular/cdk/overlay-prebuilt.css` nie jest wymagany. W otwartym
 > `KptDialog` panel trafia do `<dialog>`, bo `showModal()` przenosi go do górnej warstwy przeglądarki.
 
 ### Ikony
 
-**84 ikony są wbudowane i nie wymagają konfiguracji** — to, co rysują same komponenty, plus staple
+**84 ikony są wbudowane i nie wymagają konfiguracji** - to, co rysują same komponenty, plus staple
 powłoki aplikacji (`sun`, `moon`, `bell`, `settings`, `users`, `logout`, `layout-dashboard`,
-`home`, `activity`, `chart-bar`, `brand-github`…). Typowy panel administracyjny nie potrzebuje nic
+`home`, `activity`, `chart-bar`, `brand-github`...). Typowy panel administracyjny nie potrzebuje nic
 więcej.
 
 Pełny zestaw **Tabler Icons** (MIT, 5130 ikon) ma dwie ścieżki, a różnica jest w bundlu. Każda ikona
 jest osobnym eksportem, więc import po nazwie zostawia w bundlu wyłącznie użyte:
 
 ```tsx
-// Produkcja — do bundla wchodzą dwie ikony.
+// Produkcja - do bundla wchodzą dwie ikony.
 import { LayoutDashboard, Rocket } from '@konce-pt/react/icons';
 import { registerKptIcons } from '@konce-pt/react';
 registerKptIcons([LayoutDashboard, Rocket]);
 
-// Prototyp — wszystkie ikony, około 1,2 MB.
+// Prototyp - wszystkie ikony, około 1,2 MB.
 import { registerKptTablerIcons } from '@konce-pt/react/icons';
 registerKptTablerIcons();
 ```
 
 To `registerKptIcons` odchudza, bo przyjmuje dane argumentem i sam nie importuje pełnego zestawu.
 Z tego samego powodu `registerKptIcons(tabler)` z importem przestrzeni nazw (`import * as tabler`)
-rejestruje komplet — namespace przekazany do funkcji blokuje analizę statyczną. Rejestr jest
+rejestruje komplet - namespace przekazany do funkcji blokuje analizę statyczną. Rejestr jest
 globalny, więc wystarczy jedno wywołanie w wejściu aplikacji.
 
 ### Internacjonalizacja (i18n)
 
 Etykiety są dostępne po **angielsku (domyślnie)** i **polsku**. Bez providera wszystko renderuje się
-po angielsku — brak providera nigdy nie jest błędem. `<KptI18nProvider locale="pl">` ustawia język
+po angielsku - brak providera nigdy nie jest błędem. `<KptI18nProvider locale="pl">` ustawia język
 dla poddrzewa, `useKptI18n()` zwraca `{ locale, setLocale, messages, messagesFor, t }`, a
 `t('paginator.range', { start: 1, end: 10, total: 42 })` interpoluje `{nazwa}` i spada na EN, potem
 na sam klucz.
@@ -383,17 +422,42 @@ na EN):
 ```tsx
 import de from './i18n/de.json';
 
-<KptI18nProvider locale="de" messages={{ de }}>…</KptI18nProvider>
+<KptI18nProvider locale="de" messages={{ de }}>...</KptI18nProvider>
 ```
 
 Propsy `locale` i `dictionary` na komponencie mają priorytet nad providerem. Nazwy dni i miesięcy
 w kalendarzach pochodzą z `Intl`. Kontrakt i słowniki żyją w `@konce-pt/i18n`, wspólnym z portem
 Angulara.
 
+### Animacje
+
+Komponenty animują się od razu - sprężyny, płynne zmiany układu, wejścia i wyjścia - **bez providera**.
+`KptMotionProvider` ustawia wartości domyślne dla całej aplikacji: czy ruch w ogóle jest włączony i jaki
+rodzaj dostaje każda grupa komponentów. Każdy prop jest opcjonalny; provider pisze do `<html>`, więc
+nakładki w portalach też go słuchają.
+
+```tsx
+<KptMotionProvider layout="arc" enter="fade">...</KptMotionProvider>
+<KptMotionProvider enabled={false}>...</KptMotionProvider>   {/* bez ruchu (testy wizualne, kiosk) */}
+```
+
+| Klucz | Wartości | Komponenty (input per komponent) |
+| --- | --- | --- |
+| `enabled` | `true` \| `false` | Wszystkie. `false` zeruje też czasy w CSS (`data-kpt-motion="off"`, `--kpt-motion-scale: 0` na `<html>`); wskaźniki ładowania zwalniają zamiast stanąć |
+| `layout` | `spring` \| `arc` \| `morph` \| `none` | DataView, PickList, OrderList (`layoutMotion`) |
+| `collapse` | `spring` \| `fade` \| `none` | Accordion, Fieldset, Panel, Tree (`collapseMotion`) |
+| `enter` | `spring` \| `fade` \| `none` | Chat, ChatMessage, ChatDock, FormField (`enterMotion`); miernik hasła, chipy ChipsInput i Select |
+| `toggle` | `spring` \| `fade` \| `none` | Checkbox, RadioGroup, Switch (`toggleMotion`); gwiazdki Rating, wybór ButtonGroup |
+
+Pierwszeństwo: `enabled: false` wygrywa zawsze, potem prop samego komponentu, potem wartość z providera,
+a na końcu `spring`. Drobne reakcje (wciśnięcie przycisku, fokus i błąd pola, uchwyt suwaka) to czysty CSS
+i idą tylko za `enabled`. Systemowe "ogranicz ruch" jest respektowane zawsze. Te same sprężyny i pomocniki
+FLIP dla własnych widoków są w [`@konce-pt/motion`](https://www.npmjs.com/package/@konce-pt/motion).
+
 ### Komponenty (80+)
 
 Formularze, przyciski i akcje, layout, nawigacja, dane (z flagową `KptDataTable`), feedback
-i overlay — pełna lista w tabeli powyżej. Ciężkie rzeczy (wykresy, czat, roadmapa, mapy, pełny Tabler)
+i overlay - pełna lista w tabeli powyżej. Ciężkie rzeczy (wykresy, czat, roadmapa, mapy, pełny Tabler)
 siedzą w subpathach `@konce-pt/react/{charts,chat,roadmap,grid,map,icons}`, żeby nie obciążać rdzenia.
 Każdy komponent ma obok źródła plik `llms.txt` z opisem API.
 
@@ -404,8 +468,8 @@ Playground z demami: [ui.konce.pt/react](https://ui.konce.pt/react). Opisy API d
 [`llms-pl.txt`](https://ui.konce.pt/llms/react/llms-pl.txt) (PL). Repozytorium:
 [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui).
 
-Alerty skanerów łańcucha dostaw (Socket.dev i podobne) — klucze i18n czytane jak domeny
-oraz domyślne endpointy mapy — omawia sekcja „Skanery bezpieczeństwa" w
+Alerty skanerów łańcucha dostaw (Socket.dev i podobne) - klucze i18n czytane jak domeny
+oraz domyślne endpointy mapy - omawia sekcja "Skanery bezpieczeństwa" w
 [arkuszu projektu](https://ui.konce.pt/llms-pl.txt).
 
 ### Licencja

package/dist/accordion/accordion.d.ts

@@ -1,9 +1,17 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type KptCollapseMotion } from '@konce-pt/motion';
 export interface KptAccordionProps extends ComponentPropsWithRef<'div'> {
     /** Pozwala trzymać otwartych wiele paneli naraz. */
     multi?: boolean;
     animated?: boolean;
     animationDuration?: number;
+    /**
+     * Ruch zwijania: `spring` - wysokość na sprężynie, treść wjeżdża i wyostrza się, przy zwijaniu
+     * najpierw gaśnie; `fade` - treść się przenika; `none` - bez ruchu. Bez wartości bierze `collapse`
+     * z `KptMotionProvider` (domyślnie `spring`); `animated={false}`, `enabled={false}` i systemowe
+     * "ogranicz ruch" wyłączają go zawsze.
+     */
+    collapseMotion?: KptCollapseMotion;
     /** Indeksy otwartych paneli. */
     openIndexes?: number[];
     defaultOpenIndexes?: number[];
@@ -11,19 +19,19 @@ export interface KptAccordionProps extends ComponentPropsWithRef<'div'> {
     children?: ReactNode;
 }
 /**
- * Akordeon — grupa rozwijanych paneli. `multi` pozwala otworzyć wiele naraz.
+ * Akordeon - grupa rozwijanych paneli. `multi` pozwala otworzyć wiele naraz.
  *
- * Stan otwarcia trzyma akordeon, a panele dostają swój indeks przez klonowanie — inaczej
+ * Stan otwarcia trzyma akordeon, a panele dostają swój indeks przez klonowanie - inaczej
  * pojedynczy tryb nie miałby jak zamknąć rodzeństwa. Panel użyty samodzielnie, poza akordeonem,
  * zarządza sobą sam.
  *
  * @example
  * <KptAccordion>
- *   <KptAccordion.Panel title="Sekcja 1">…</KptAccordion.Panel>
- *   <KptAccordion.Panel title="Sekcja 2">…</KptAccordion.Panel>
+ *   <KptAccordion.Panel title="Sekcja 1">...</KptAccordion.Panel>
+ *   <KptAccordion.Panel title="Sekcja 2">...</KptAccordion.Panel>
  * </KptAccordion>
  */
-export declare function KptAccordion({ multi, animated, animationDuration, openIndexes, defaultOpenIndexes, onOpenIndexesChange, className, children, ...rest }: Readonly<KptAccordionProps>): import("react").JSX.Element;
+export declare function KptAccordion({ multi, animated, animationDuration, collapseMotion, openIndexes, defaultOpenIndexes, onOpenIndexesChange, className, children, ...rest }: Readonly<KptAccordionProps>): import("react").JSX.Element;
 export declare namespace KptAccordion {
     var Panel: typeof KptAccordionPanel;
 }
@@ -34,7 +42,7 @@ export interface KptAccordionPanelProps extends Omit<ComponentPropsWithRef<'div'
     expanded?: boolean;
     defaultExpanded?: boolean;
     onExpandedChange?: (expanded: boolean) => void;
-    /** Wstawiany przez akordeon — nie podawaj ręcznie. */
+    /** Wstawiany przez akordeon - nie podawaj ręcznie. */
     index?: number;
     children?: ReactNode;
 }

package/dist/accordion/accordion.js

@@ -1,24 +1,29 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, cloneElement, createContext, isValidElement, useContext, useState, } from 'react';
+import { cloneElement, createContext, isValidElement, useContext, } from 'react';
 import { cn } from "../internal/cn.js";
+import { slotChildren } from "../internal/slot-children.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptId } from "../internal/use-id.js";
 import { KptIcon } from "../icon/icon.js";
+import { resolveCollapseMotion } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
 const AccordionContext = createContext(null);
 /**
- * Akordeon — grupa rozwijanych paneli. `multi` pozwala otworzyć wiele naraz.
+ * Akordeon - grupa rozwijanych paneli. `multi` pozwala otworzyć wiele naraz.
  *
- * Stan otwarcia trzyma akordeon, a panele dostają swój indeks przez klonowanie — inaczej
+ * Stan otwarcia trzyma akordeon, a panele dostają swój indeks przez klonowanie - inaczej
  * pojedynczy tryb nie miałby jak zamknąć rodzeństwa. Panel użyty samodzielnie, poza akordeonem,
  * zarządza sobą sam.
  *
  * @example
  * <KptAccordion>
- *   <KptAccordion.Panel title="Sekcja 1">…</KptAccordion.Panel>
- *   <KptAccordion.Panel title="Sekcja 2">…</KptAccordion.Panel>
+ *   <KptAccordion.Panel title="Sekcja 1">...</KptAccordion.Panel>
+ *   <KptAccordion.Panel title="Sekcja 2">...</KptAccordion.Panel>
  * </KptAccordion>
  */
-export function KptAccordion({ multi = false, animated = true, animationDuration = 500, openIndexes, defaultOpenIndexes = [], onOpenIndexesChange, className, children, ...rest }) {
+export function KptAccordion({ multi = false, animated = true, animationDuration = 500, collapseMotion, openIndexes, defaultOpenIndexes = [], onOpenIndexesChange, className, children, ...rest }) {
+    const motionConfig = useKptMotion();
     const [open, setOpen] = useControllableState({
         value: openIndexes,
         defaultValue: defaultOpenIndexes,
@@ -33,20 +38,23 @@ export function KptAccordion({ multi = false, animated = true, animationDuration
                 setOpen(multi ? [...open, index] : [index]);
         },
         animMs: `${animated ? animationDuration : 0}ms`,
+        motion: resolveCollapseMotion(collapseMotion, motionConfig, animated),
     };
-    let index = -1;
-    const panels = Children.map(children, (child) => {
-        if (!isValidElement(child) || child.type?.kptAccordionSlot !== 'panel') {
-            return child;
-        }
-        index += 1;
-        return cloneElement(child, { index });
-    });
+    // Indeks panelu = liczba paneli przed nim; fragmenty rozwinięte, więc panel z warunku też się liczy.
+    const items = slotChildren(children);
+    const isPanel = (child) => isValidElement(child) && child.type?.kptAccordionSlot === 'panel';
+    const panelIndex = items.map((_, at) => items.slice(0, at).filter(isPanel).length);
+    const panels = items.map((child, at) => isPanel(child)
+        ? cloneElement(child, { key: child.key ?? `panel-${panelIndex[at]}`, index: panelIndex[at] })
+        : isValidElement(child) ? cloneElement(child, { key: child.key ?? `child-${at}` }) : child);
     return (_jsx(AccordionContext.Provider, { value: context, children: _jsx("div", { className: cn('kpt-accordion-host', className), ...rest, children: panels }) }));
 }
 /** Panel akordeonu. Umieszczaj w `<KptAccordion>` albo używaj samodzielnie. */
 export function KptAccordionPanel({ title, disabled = false, expanded, defaultExpanded = false, onExpandedChange, index, className, style, children, ...rest }) {
     const accordion = useContext(AccordionContext);
+    const motionConfig = useKptMotion();
+    // Panel poza akordeonem zachowuje się jak w akordeonie z domyślną konfiguracją.
+    const motion = accordion?.motion ?? resolveCollapseMotion(undefined, motionConfig);
     const uid = useKptId(undefined, 'kpt-accordion');
     const headerId = `${uid}-header`;
     const bodyId = `${uid}-body`;
@@ -67,9 +75,9 @@ export function KptAccordionPanel({ title, disabled = false, expanded, defaultEx
             setStandalone(willOpen);
         onExpandedChange?.(willOpen);
     };
-    return (_jsx("div", { className: cn('kpt-accordion-panel-host', className), style: { ['--kpt-anim-duration']: accordion?.animMs ?? '500ms', ...style }, ...rest, children: _jsxs("div", { className: cn('kpt-accordion-panel', isOpen && 'is-open'), children: [_jsxs("button", { type: "button", className: "kpt-accordion-panel__header", id: headerId, "aria-expanded": isOpen, "aria-controls": bodyId, disabled: disabled, onClick: toggle, children: [_jsx("span", { className: "kpt-accordion-panel__title", children: title }), _jsx(KptIcon, { name: "chevron-down", className: cn('kpt-accordion-panel__chevron', isOpen && 'is-open') })] }), _jsx("div", { className: cn('kpt-accordion-panel__collapse', isOpen && 'is-open'), 
-                    // Treść to region nazwany nagłówkiem — czytnik ogłasza nie tylko stan, ale i to, czego dotyczy.
-                    role: "region", id: bodyId, "aria-labelledby": headerId, inert: !isOpen, "aria-hidden": !isOpen, children: _jsx("div", { className: "kpt-accordion-panel__collapse-inner", children: _jsx("div", { className: "kpt-accordion-panel__body", children: children }) }) })] }) }));
+    return (_jsx("div", { className: cn('kpt-accordion-panel-host', className), style: { ['--kpt-anim-duration']: accordion?.animMs ?? '500ms', ...style }, ...rest, children: _jsxs("div", { className: cn('kpt-accordion-panel', isOpen && 'is-open'), "data-motion": motion, children: [_jsxs("button", { type: "button", className: "kpt-accordion-panel__header", id: headerId, "aria-expanded": isOpen, "aria-controls": bodyId, disabled: disabled, onClick: toggle, children: [_jsx("span", { className: "kpt-accordion-panel__title", children: title }), _jsx(KptIcon, { name: "chevron-down", className: cn('kpt-accordion-panel__chevron', isOpen && 'is-open') })] }), _jsx("div", { className: cn('kpt-accordion-panel__collapse', isOpen && 'is-open'), 
+                    // Treść to region nazwany nagłówkiem - czytnik ogłasza nie tylko stan, ale i to, czego dotyczy.
+                    role: "region", id: bodyId, "aria-labelledby": headerId, inert: !isOpen, children: _jsx("div", { className: "kpt-accordion-panel__collapse-inner", children: _jsx("div", { className: "kpt-accordion-panel__body", children: children }) }) })] }) }));
 }
 KptAccordionPanel.kptAccordionSlot = 'panel';
 KptAccordion.Panel = KptAccordionPanel;

package/dist/accordion/llms.txt

@@ -1,6 +1,6 @@
 # KptAccordion (@konce-pt/react)
 
-An accordion — a group of expandable panels. `multi` allows several open at once.
+An accordion - a group of expandable panels. `multi` allows several open at once.
 Import: `import { KptAccordion } from '@konce-pt/react';`
 
 ## DOM
@@ -10,12 +10,12 @@ Import: `import { KptAccordion } from '@konce-pt/react';`
           <button class="kpt-accordion-panel__header" id="kpt-accordion-r1-header"
                   aria-expanded="true" aria-controls="kpt-accordion-r1-body">
             <span class="kpt-accordion-panel__title">Section 1</span>
-            <span class="kpt-icon-host kpt-accordion-panel__chevron is-open">…</span>
+            <span class="kpt-icon-host kpt-accordion-panel__chevron is-open">...</span>
           </button>
           <div class="kpt-accordion-panel__collapse is-open" role="region" id="kpt-accordion-r1-body"
                aria-labelledby="kpt-accordion-r1-header">
             <div class="kpt-accordion-panel__collapse-inner">
-              <div class="kpt-accordion-panel__body">…children…</div>
+              <div class="kpt-accordion-panel__body">...children...</div>
             </div>
           </div>
         </div>
@@ -23,17 +23,18 @@ Import: `import { KptAccordion } from '@konce-pt/react';`
     </div>
 
 ## KptAccordion props
-- `multi`: boolean — several panels open at once
-- `openIndexes` / `defaultOpenIndexes` / `onOpenIndexesChange` — the open state, by index
+- `multi`: boolean - several panels open at once
+- `openIndexes` / `defaultOpenIndexes` / `onOpenIndexesChange` - the open state, by index
 - `animated`: boolean (default true), `animationDuration`: number (ms, default 500)
+- `collapseMotion`: `'spring' | 'fade' | 'none'` (default from `KptMotionProvider`, else `spring`) - see "Collapse motion"
 
 ## KptAccordion.Panel props
 - `title` (required), `disabled`
-- `expanded` / `defaultExpanded` / `onExpandedChange` — used when the panel stands alone
+- `expanded` / `defaultExpanded` / `onExpandedChange` - used when the panel stands alone
 - `children`
 
 ## Who owns the state
-The accordion owns it, and panels receive their index by cloning — without that, single mode would
+The accordion owns it, and panels receive their index by cloning - without that, single mode would
 have no way to close its siblings. A panel used outside an accordion falls back to its own state, so
 it works standalone with no extra wrapper.
 
@@ -43,11 +44,22 @@ nothing inside takes focus or reaches a screen reader.
 
 ## Examples
     <KptAccordion defaultOpenIndexes={[0]}>
-      <KptAccordion.Panel title="Section 1">…</KptAccordion.Panel>
-      <KptAccordion.Panel title="Section 2">…</KptAccordion.Panel>
+      <KptAccordion.Panel title="Section 1">...</KptAccordion.Panel>
+      <KptAccordion.Panel title="Section 2">...</KptAccordion.Panel>
     </KptAccordion>
 
-    <KptAccordion multi openIndexes={open} onOpenIndexesChange={setOpen}>…</KptAccordion>
+    <KptAccordion multi openIndexes={open} onOpenIndexesChange={setOpen}>...</KptAccordion>
+
+## Collapse motion
+- `spring` - the height opens on a soft spring, the content slides in from above and sharpens out
+  of a blur; when collapsing, the content fades first and only then the section closes. The chevron
+  turns on a spring.
+- `fade` - the height on the standard curve, the content cross-fades.
+- `none` - the state changes without motion.
+
+With no value it takes `collapse` from `KptMotionProvider` (default `spring`). `animated={false}` on the accordion, `enabled: false`
+in the config and the system "reduce motion" setting always turn it off. `animationDuration` sets
+the time of every kind. Pure CSS: the kind sits in `data-motion` on the component root.
 
 ## Tokens
 `--kpt-color-border`, `--kpt-color-surface`, `--kpt-motion-easing-standard`, plus

package/dist/alert/alert.d.ts

@@ -22,10 +22,10 @@ export interface KptAlertProps extends Omit<ComponentPropsWithRef<'div'>, 'title
  * go. `visible`/`onVisibleChange` pozwalają pokazać go ponownie z zewnątrz.
  *
  * Rola idzie za wagą komunikatu: `info` i `success` to `role="status"` (czytnik ogłosi je uprzejmie,
- * nie przerywając), `warning` i `danger` — `role="alert"` (natychmiast).
+ * nie przerywając), `warning` i `danger` - `role="alert"` (natychmiast).
  *
  * @example
  * <KptAlert variant="success" title="Zapisano">Zmiany zostały zapisane.</KptAlert>
- * <KptAlert variant="warning" dismissible onClosed={onClosed}>Uwaga…</KptAlert>
+ * <KptAlert variant="warning" dismissible onClosed={onClosed}>Uwaga...</KptAlert>
  */
 export declare function KptAlert({ variant, title, dismissible, onClosed, visible, defaultVisible, onVisibleChange, locale, dictionary, className, children, ...rest }: Readonly<KptAlertProps>): import("react").JSX.Element;