@konce-pt/motion 0.0.0-stage → 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konce.pt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI - Angular component library" width="100%" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @konce-pt/motion
+
+Rdzeń ruchu [Koncept UI](https://gitlab.com/konce-pt/koncept-ui): krzywe sprężyn do `linear()`,
+plany lotów FLIP przy zmianie układu, globalna konfiguracja ruchu i mała warstwa DOM, która te loty
+odgrywa. Czysty TypeScript, **zero zależności runtime**, bez wiązania z frameworkiem.
+
+Zwykle nie instalujesz go samodzielnie: to zależność `@konce-pt/angular` i `@konce-pt/react`,
+a konfigurację ustawia się przez `provideKptMotion` / `KptMotionProvider` (patrz README portów).
+Sięgnij po niego wprost, gdy własny widok ma się ruszać tak samo jak komponenty biblioteki.
+
+```bash
+npm i @konce-pt/motion
+```
+
+```ts
+import { planLayoutMotion, resolveLayoutMotion, springEasing } from '@konce-pt/motion';
+
+// Sprężyna jako krzywa CSS - do transition-timing-function.
+springEasing(0.32); // 'linear(0, ..., 1)'
+
+// Jaki ruch dostaje komponent: wyłączenie globalne > input > domyślny z konfiguracji > spring.
+resolveLayoutMotion(undefined, { layout: 'arc' }); // 'arc'
+resolveLayoutMotion('arc', { enabled: false }); // 'none'
+
+// Klatki lotu FLIP z prostokątów przed i po zmianie układu.
+const flights = planLayoutMotion(before, after, { motion: 'spring', radius: 8 });
+```
+
+## Konfiguracja
+
+`KptMotionConfig` ma pięć opcjonalnych kluczy: `enabled` oraz domyślny rodzaj ruchu dla czterech grup
+komponentów - `layout` (`spring | arc | morph | none`), `collapse`, `enter` i `toggle`
+(`spring | fade | none`). Funkcje `resolve*Motion(input, config)` rozstrzygają, co dostaje komponent:
+`enabled: false` > input komponentu > wartość z konfiguracji > `spring`. `applyMotionConfig` przy
+`enabled: false` stawia na korzeniu `data-kpt-motion="off"` i zeruje `--kpt-motion-scale` oraz czasy
+`--kpt-motion-duration-*` - tak gaśnie ruch zapisany w samym CSS.
+
+## API
+
+- **Konfiguracja** - `resolveLayoutMotion`, `resolveCollapseMotion`, `resolveEnterMotion`, `resolveToggleMotion`,
+  `motionRootStyle`, stałe `KPT_DEFAULT_*_MOTION`, typy `KptMotionConfig`, `KptLayoutMotion`,
+  `KptCollapseMotion`, `KptEnterMotion`, `KptToggleMotion`
+- **Sprężyny** - `springProgress`, `springEasing`
+- **Loty układu** - `planLayoutMotion`, `layoutMotionDuration`, typy `KptRect`, `KptLayoutFlight`
+- **Warstwa DOM** - `snapshotLayout`, `playLayoutMotion`, `stopLayoutMotion`, `morphLayout`,
+  `applyMotionConfig`, `layoutMotionAllowed`, `layoutMorphSupported`
+- **Mikroruch** - `playEnterMotion`, `playShakeMotion`, `playPopMotion`, `playInvalidMotion`,
+  `playIndicatorMotion`
+- **Listy z kluczem** - `snapshotKeyed`, `playKeyedMotion`, `stopKeyedMotion`, `morphKeyed`,
+  `isVisibleInScroller`, `revealInScroller`
+- **Zawijany wiersz (tagi, chipy)** - `prepareFlowMotion`, `flowChangeOf`, typ `KptFlowChange`
+- **Kreator i podmiana treści** - `stepperSchedule`, `stepperScheduleOptions`, `playStepperLight`, `preparePanelSwap`, typy
+  `KptStepperSchedule`, `KptStepTiming`
+
+Pełny opis: [`llms.txt`](https://ui.konce.pt/llms/motion/llms.txt) (EN)
+i [`llms-pl.txt`](https://ui.konce.pt/llms/motion/llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/motion exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/config.d.ts

@@ -0,0 +1,71 @@
+import type { KptLayoutMotion } from './layout.ts';
+/**
+ * Ruch zwijania sekcji (`kpt-accordion`, `kpt-fieldset`, `kpt-panel`): `spring` - wysokość na
+ * miękkiej sprężynie, treść wjeżdża z przesunięciem i rozmyciem, a przy zwijaniu najpierw gaśnie;
+ * `fade` - wysokość na zwykłej krzywej, treść się przenika; `none` - bez ruchu.
+ */
+export type KptCollapseMotion = 'spring' | 'fade' | 'none';
+/**
+ * Ruch pojawiania się (nowa wiadomość czatu, reakcja, okno docka): `spring` - element wyrasta
+ * z miejsca, z którego przychodzi, na sprężynie; `fade` - tylko się przenika; `none` - bez ruchu.
+ */
+export type KptEnterMotion = 'spring' | 'fade' | 'none';
+/**
+ * Ruch przełączania (`kpt-checkbox`, `kpt-radio-group`, `kpt-switch`): `spring` - pole wskakuje,
+ * ptaszek rysuje się kreską, kciuk jedzie na sprężynie; `fade` - spokojne przejście koloru i znaku;
+ * `none` - bez ruchu.
+ */
+export type KptToggleMotion = 'spring' | 'fade' | 'none';
+/**
+ * Globalne ustawienie ruchu Koncept UI - jedno dla całej aplikacji (Angular:
+ * `provideKptMotion(...)`, React: `<KptMotionProvider>`). Brak konfiguracji = ruch włączony
+ * z wartościami domyślnymi; systemowe "ogranicz ruch" jest respektowane zawsze.
+ */
+export interface KptMotionConfig {
+    /**
+     * `false` wyłącza ruch wszystkich komponentów: przejścia CSS dostają czas 0, a ruch sterowany
+     * z kodu (np. zmiana układu `kpt-data-view`) się nie odpala. Wskaźniki ładowania (spinner,
+     * nieokreślony postęp, połysk szkieletu) zwalniają zamiast stanąć. Domyślnie `true`.
+     */
+    enabled?: boolean;
+    /** Domyślny ruch zmiany układu dla komponentów, które go mają (`kpt-data-view`). Domyślnie `spring`. */
+    layout?: KptLayoutMotion;
+    /** Domyślny ruch zwijania sekcji (`kpt-accordion`, `kpt-fieldset`, `kpt-panel`). Domyślnie `spring`. */
+    collapse?: KptCollapseMotion;
+    /** Domyślny ruch pojawiania się (czat: wiadomości, reakcje, status, dock). Domyślnie `spring`. */
+    enter?: KptEnterMotion;
+    /** Domyślny ruch przełączania (checkbox, radio, switch). Domyślnie `spring`. */
+    toggle?: KptToggleMotion;
+}
+/** Co konfiguracja nakłada na korzeń dokumentu: atrybut i zmienne CSS. */
+export interface KptMotionRootStyle {
+    /** Wartość `data-kpt-motion` albo `null`, gdy atrybutu ma nie być. */
+    attribute: 'off' | null;
+    properties: Readonly<Record<string, string>>;
+}
+export declare const KPT_DEFAULT_LAYOUT_MOTION: KptLayoutMotion;
+export declare const KPT_DEFAULT_COLLAPSE_MOTION: KptCollapseMotion;
+export declare const KPT_DEFAULT_ENTER_MOTION: KptEnterMotion;
+export declare const KPT_DEFAULT_TOGGLE_MOTION: KptToggleMotion;
+/**
+ * Ruch zmiany układu dla jednego komponentu. Kolejność: wyłączenie globalne wygrywa ze wszystkim,
+ * potem jawny input komponentu, potem domyślny `layout` z konfiguracji, na końcu `spring`.
+ * Systemowe "ogranicz ruch" sprawdza warstwa DOM w chwili zmiany (może się zmienić w trakcie).
+ */
+export declare function resolveLayoutMotion(input?: KptLayoutMotion | null, config?: KptMotionConfig | null): KptLayoutMotion;
+/**
+ * Ruch zwijania dla jednej sekcji. Kolejność: wyłączenie globalne, potem dawne `animated: false`
+ * komponentu (zostaje jako wyłącznik), potem jawny input, domyślny `collapse` z konfiguracji
+ * i na końcu `spring`. Systemowe "ogranicz ruch" gasi go w CSS (`@media`), nie tutaj.
+ */
+export declare function resolveCollapseMotion(input?: KptCollapseMotion | null, config?: KptMotionConfig | null, animated?: boolean): KptCollapseMotion;
+/** Ruch pojawiania się: wyłączenie globalne > input komponentu > `enter` z konfiguracji > `spring`. */
+export declare function resolveEnterMotion(input?: KptEnterMotion | null, config?: KptMotionConfig | null): KptEnterMotion;
+/** Ruch przełączania: wyłączenie globalne > input komponentu > `toggle` z konfiguracji > `spring`. */
+export declare function resolveToggleMotion(input?: KptToggleMotion | null, config?: KptMotionConfig | null): KptToggleMotion;
+/**
+ * Zmienne nakładane na `:root` przy wyłączonym ruchu. `--kpt-motion-scale` mnoży czasy wpisane
+ * w komponentach (`calc(0.2s * var(--kpt-motion-scale, 1))`), a zerowe tokeny czasu gaszą
+ * resztę - razem bez jednego `!important` i bez dodatkowego arkusza.
+ */
+export declare function motionRootStyle(config?: KptMotionConfig | null): KptMotionRootStyle;

package/dist/config.js

@@ -0,0 +1,54 @@
+export const KPT_DEFAULT_LAYOUT_MOTION = 'spring';
+export const KPT_DEFAULT_COLLAPSE_MOTION = 'spring';
+export const KPT_DEFAULT_ENTER_MOTION = 'spring';
+export const KPT_DEFAULT_TOGGLE_MOTION = 'spring';
+/**
+ * Ruch zmiany układu dla jednego komponentu. Kolejność: wyłączenie globalne wygrywa ze wszystkim,
+ * potem jawny input komponentu, potem domyślny `layout` z konfiguracji, na końcu `spring`.
+ * Systemowe "ogranicz ruch" sprawdza warstwa DOM w chwili zmiany (może się zmienić w trakcie).
+ */
+export function resolveLayoutMotion(input, config) {
+    if (config?.enabled === false)
+        return 'none';
+    return input ?? config?.layout ?? KPT_DEFAULT_LAYOUT_MOTION;
+}
+/**
+ * Ruch zwijania dla jednej sekcji. Kolejność: wyłączenie globalne, potem dawne `animated: false`
+ * komponentu (zostaje jako wyłącznik), potem jawny input, domyślny `collapse` z konfiguracji
+ * i na końcu `spring`. Systemowe "ogranicz ruch" gasi go w CSS (`@media`), nie tutaj.
+ */
+export function resolveCollapseMotion(input, config, animated = true) {
+    if (config?.enabled === false || !animated)
+        return 'none';
+    return input ?? config?.collapse ?? KPT_DEFAULT_COLLAPSE_MOTION;
+}
+/** Ruch pojawiania się: wyłączenie globalne > input komponentu > `enter` z konfiguracji > `spring`. */
+export function resolveEnterMotion(input, config) {
+    if (config?.enabled === false)
+        return 'none';
+    return input ?? config?.enter ?? KPT_DEFAULT_ENTER_MOTION;
+}
+/** Ruch przełączania: wyłączenie globalne > input komponentu > `toggle` z konfiguracji > `spring`. */
+export function resolveToggleMotion(input, config) {
+    if (config?.enabled === false)
+        return 'none';
+    return input ?? config?.toggle ?? KPT_DEFAULT_TOGGLE_MOTION;
+}
+/**
+ * Zmienne nakładane na `:root` przy wyłączonym ruchu. `--kpt-motion-scale` mnoży czasy wpisane
+ * w komponentach (`calc(0.2s * var(--kpt-motion-scale, 1))`), a zerowe tokeny czasu gaszą
+ * resztę - razem bez jednego `!important` i bez dodatkowego arkusza.
+ */
+export function motionRootStyle(config) {
+    if (config?.enabled !== false)
+        return { attribute: null, properties: {} };
+    return {
+        attribute: 'off',
+        properties: {
+            '--kpt-motion-scale': '0',
+            '--kpt-motion-duration-fast': '0ms',
+            '--kpt-motion-duration-base': '0ms',
+            '--kpt-motion-duration-slow': '0ms',
+        },
+    };
+}

package/dist/dom.d.ts

@@ -0,0 +1,86 @@
+import { type KptMotionConfig } from './config.ts';
+import { type KptRect } from './layout.ts';
+/**
+ * Warstwa DOM ruchu układu - wspólna dla obu portów, bo pomiar, odtworzenie lotów i morf są
+ * identyczne w Angularze i Reakcie; różni je tylko to, jak framework wymusza wyrenderowanie
+ * nowego stanu. Bez testów jednostkowych (potrzebuje przeglądarki); logika liczb siedzi
+ * w `layout.ts` i tam jest testowana.
+ */
+/** Stan układu przed zmianą, zmierzony z ekranu (razem z trwającym ruchem). */
+export interface KptLayoutSnapshot {
+    rects: KptRect[];
+    height: number;
+    /** Środek elementu, który wywołał zmianę - stąd rusza fala w `arc`. */
+    origin?: {
+        x: number;
+        y: number;
+    };
+}
+export interface KptPlayLayoutOptions {
+    motion: 'spring' | 'arc';
+    /** Klasa na czas lotu (np. `overflow: clip`, `z-index`); zdejmowana po wylądowaniu. */
+    movingClass: string;
+    /** Element kontr-skalowany wewnątrz elementu (zwykle jego jedyne dziecko). */
+    innerOf: (item: HTMLElement) => HTMLElement | null;
+}
+/** Ruch układu ma sens tylko w przeglądarce z WAAPI i bez systemowego "ogranicz ruch". */
+export declare function layoutMotionAllowed(): boolean;
+/** Morf wymaga View Transitions (same-document); bez nich zmiana dzieje się od razu. */
+export declare function layoutMorphSupported(): boolean;
+/** Mierzy elementy względem kontenera; `getBoundingClientRect` celowo z transformem. */
+export declare function snapshotLayout(container: HTMLElement, items: readonly HTMLElement[], originEl?: Element | null): KptLayoutSnapshot;
+/** Zatrzymuje trwający ruch układu. Wołać PO pomiarze - wtedy nowy lot startuje z ekranu. */
+export declare function stopLayoutMotion(container: HTMLElement, movingClass: string): void;
+/**
+ * Gra loty od `first` do bieżącego (już wyrenderowanego) układu. Zwraca czas całości w ms.
+ * Kolor cienia w `arc` i promień rogu bierze z obliczonych stylów, więc idą za motywem.
+ */
+export declare function playLayoutMotion(container: HTMLElement, items: readonly HTMLElement[], first: KptLayoutSnapshot, options: KptPlayLayoutOptions): number;
+/**
+ * Natywny morf (View Transitions): nadaje elementom unikalne `view-transition-name` na czas
+ * przejścia, woła `update` w środku `startViewTransition` i zdejmuje nazwy po końcu.
+ * `update` MUSI zsynchronizować DOM przed powrotem (Angular: `detectChanges()`, React:
+ * `flushSync`) - przeglądarka robi zrzut nowego stanu zaraz po nim.
+ * Bez wsparcia przeglądarki albo przy "ogranicz ruch" po prostu woła `update`.
+ */
+export declare function morphLayout(items: readonly HTMLElement[], namePrefix: string, className: string, update: () => void): void;
+/**
+ * Nakłada globalną konfigurację ruchu na korzeń dokumentu (`data-kpt-motion` + zmienne CSS)
+ * i zwraca funkcję, która cofa dokładnie to, co ustawiła.
+ */
+export declare function applyMotionConfig(root: HTMLElement, config?: KptMotionConfig | null): () => void;
+/** Skąd element przychodzi: z dołu (własna wiadomość z pola pisania) albo od strony nadawcy. */
+export type KptEnterFrom = 'below' | 'start' | 'end';
+/**
+ * Wejście elementu, który już jest w DOM (WAAPI, bez klas): `spring` - wyrasta z kierunku `from`
+ * na sprężynie i wyostrza się z rozmycia, `fade` - tylko się przenika. `start`/`end` idą za
+ * kierunkiem pisma (RTL odwraca stronę). Bez WAAPI albo przy "ogranicz ruch" nic nie robi.
+ */
+export declare function playEnterMotion(element: HTMLElement, motion: 'spring' | 'fade', from: KptEnterFrom, delay?: number): void;
+/**
+ * Potrząśnięcie w poziomie - sygnał "nie tak" (pole staje się nieprawidłowe). Krótkie i gasnące,
+ * żeby nie męczyło przy kolejnych próbach; amplituda w px, czas ~0,36 s. Bez WAAPI albo przy
+ * "ogranicz ruch" nic nie robi - stan i tak niesie kolor i komunikat.
+ */
+export declare function playShakeMotion(element: HTMLElement, amplitude?: number): void;
+/**
+ * Wskoczenie (pop) - element przysiada i odbija na sprężynie. Odpalane z handlera zmiany, nie z CSS:
+ * reguła na `:checked` zagrałaby też przy pierwszym renderze. `squash` rozciąga element w poziomie
+ * zamiast go zmniejszać (kciuk przełącznika w ruchu). Przy "ogranicz ruch" nic nie robi.
+ */
+export declare function playPopMotion(element: HTMLElement, mode?: 'pop' | 'squash'): void;
+/**
+ * Sygnał błędu kontrolki: pierścień w kolorze błędu rozchodzi się od elementu i gaśnie, a element
+ * krótko się potrząsa (\`shake: false\` - sam pierścień, np. gdy potrząsa już otaczający
+ * \`kpt-form-field\`). Kolor z tokenu \`--kpt-form-field-border-error\` (zapas: \`--kpt-color-danger\`),
+ * więc idzie za motywem. Przy "ogranicz ruch" nic nie robi - błąd i tak niesie kolor ramki.
+ */
+export declare function playInvalidMotion(element: HTMLElement, options?: {
+    shake?: boolean;
+}): void;
+/**
+ * Wskaźnik wyboru w kontrolce segmentowej: tło aktywnej pozycji (pseudo-element `pseudo`) przejeżdża
+ * z miejsca i szerokości poprzedniej pozycji (`from`, zmierzone przed zmianą) na nową - FLIP samego
+ * pseudo-elementu, bez dodatkowego węzła w DOM. Przy "ogranicz ruch" nic nie robi.
+ */
+export declare function playIndicatorMotion(from: DOMRect, to: HTMLElement, pseudo?: string): void;

package/dist/dom.js

@@ -0,0 +1,210 @@
+import { motionRootStyle } from "./config.js";
+import { layoutMotionDuration, planLayoutMotion } from "./layout.js";
+import { springEasing } from "./spring.js";
+/** Identyfikator naszych animacji - sprzątamy tylko je, nie ruch, który ma treść elementu. */
+const ANIMATION_ID = 'kpt-layout-motion';
+/** Ruch układu ma sens tylko w przeglądarce z WAAPI i bez systemowego "ogranicz ruch". */
+export function layoutMotionAllowed() {
+    if (typeof window === 'undefined' || typeof Element === 'undefined')
+        return false;
+    if (typeof Element.prototype.animate !== 'function')
+        return false;
+    return !window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+}
+/** Morf wymaga View Transitions (same-document); bez nich zmiana dzieje się od razu. */
+export function layoutMorphSupported() {
+    return layoutMotionAllowed() && typeof document.startViewTransition === 'function';
+}
+/** Mierzy elementy względem kontenera; `getBoundingClientRect` celowo z transformem. */
+export function snapshotLayout(container, items, originEl) {
+    const box = container.getBoundingClientRect();
+    const rects = items.map((el) => {
+        const r = el.getBoundingClientRect();
+        return { x: r.left - box.left, y: r.top - box.top, width: r.width, height: r.height };
+    });
+    const snapshot = { rects, height: box.height };
+    if (originEl) {
+        const r = originEl.getBoundingClientRect();
+        snapshot.origin = { x: r.left - box.left + r.width / 2, y: r.top - box.top + r.height / 2 };
+    }
+    return snapshot;
+}
+/** Zatrzymuje trwający ruch układu. Wołać PO pomiarze - wtedy nowy lot startuje z ekranu. */
+export function stopLayoutMotion(container, movingClass) {
+    for (const a of container.getAnimations({ subtree: true }))
+        if (a.id === ANIMATION_ID)
+            a.cancel();
+    for (const el of container.querySelectorAll(`.${movingClass}`))
+        el.classList.remove(movingClass);
+}
+/**
+ * Gra loty od `first` do bieżącego (już wyrenderowanego) układu. Zwraca czas całości w ms.
+ * Kolor cienia w `arc` i promień rogu bierze z obliczonych stylów, więc idą za motywem.
+ */
+export function playLayoutMotion(container, items, first, options) {
+    const last = snapshotLayout(container, items);
+    const sample = items[0];
+    const radius = sample ? Number.parseFloat(getComputedStyle(sample).borderTopLeftRadius) || 0 : 0;
+    const scrim = getComputedStyle(container).getPropertyValue('--kpt-color-overlay-scrim').trim();
+    const flights = planLayoutMotion(first.rects, last.rects, {
+        motion: options.motion,
+        radius,
+        ...(first.origin ? { origin: first.origin } : {}),
+        ...(scrim ? { shadowColor: `color-mix(in srgb, ${scrim} 55%, transparent)` } : {}),
+    });
+    for (const flight of flights) {
+        const el = items[flight.index];
+        if (!el)
+            continue;
+        const timing = {
+            id: ANIMATION_ID,
+            duration: flight.duration,
+            delay: flight.delay,
+            easing: 'linear',
+            fill: 'backwards',
+        };
+        el.classList.add(options.movingClass);
+        const anim = el.animate(flight.item.map((f) => ({ ...f })), timing);
+        options.innerOf(el)?.animate(flight.inner.map((f) => ({ ...f })), timing);
+        const land = () => {
+            const flying = el.getAnimations().some((a) => a.id === ANIMATION_ID && a.playState === 'running');
+            if (!flying)
+                el.classList.remove(options.movingClass);
+        };
+        anim.finished.then(land, () => undefined);
+    }
+    // Kontener zmienia wysokość razem z kartami, zamiast skakać pod nimi.
+    if (Math.abs(first.height - last.height) > 1) {
+        const easing = getComputedStyle(container).getPropertyValue('--kpt-motion-easing-emphasized').trim() || 'ease';
+        container.animate({ height: [`${first.height}px`, `${last.height}px`] }, { id: ANIMATION_ID, duration: options.motion === 'arc' ? 640 : 520, easing });
+    }
+    return layoutMotionDuration(flights);
+}
+/**
+ * Natywny morf (View Transitions): nadaje elementom unikalne `view-transition-name` na czas
+ * przejścia, woła `update` w środku `startViewTransition` i zdejmuje nazwy po końcu.
+ * `update` MUSI zsynchronizować DOM przed powrotem (Angular: `detectChanges()`, React:
+ * `flushSync`) - przeglądarka robi zrzut nowego stanu zaraz po nim.
+ * Bez wsparcia przeglądarki albo przy "ogranicz ruch" po prostu woła `update`.
+ */
+export function morphLayout(items, namePrefix, className, update) {
+    if (!layoutMorphSupported()) {
+        update();
+        return;
+    }
+    items.forEach((el, i) => {
+        el.style.viewTransitionName = `${namePrefix}-${i}`;
+        el.style.viewTransitionClass = className;
+    });
+    const clear = () => {
+        for (const el of items) {
+            el.style.viewTransitionName = '';
+            el.style.viewTransitionClass = '';
+        }
+    };
+    document.startViewTransition(update).finished.then(clear, clear);
+}
+/**
+ * Nakłada globalną konfigurację ruchu na korzeń dokumentu (`data-kpt-motion` + zmienne CSS)
+ * i zwraca funkcję, która cofa dokładnie to, co ustawiła.
+ */
+export function applyMotionConfig(root, config) {
+    const { attribute, properties } = motionRootStyle(config);
+    if (attribute)
+        root.setAttribute('data-kpt-motion', attribute);
+    for (const [name, value] of Object.entries(properties))
+        root.style.setProperty(name, value);
+    return () => {
+        if (attribute)
+            root.removeAttribute('data-kpt-motion');
+        for (const name of Object.keys(properties))
+            root.style.removeProperty(name);
+    };
+}
+/**
+ * Wejście elementu, który już jest w DOM (WAAPI, bez klas): `spring` - wyrasta z kierunku `from`
+ * na sprężynie i wyostrza się z rozmycia, `fade` - tylko się przenika. `start`/`end` idą za
+ * kierunkiem pisma (RTL odwraca stronę). Bez WAAPI albo przy "ogranicz ruch" nic nie robi.
+ */
+export function playEnterMotion(element, motion, from, delay = 0) {
+    if (!layoutMotionAllowed())
+        return;
+    const timing = { id: ANIMATION_ID, delay, fill: 'backwards' };
+    if (motion === 'fade') {
+        element.animate({ opacity: [0, 1] }, { ...timing, duration: 260, easing: 'ease-out' });
+        return;
+    }
+    const rtl = getComputedStyle(element).direction === 'rtl';
+    const side = (from === 'end') !== rtl ? 1 : -1;
+    const start = from === 'below' ? 'translate(0, 18px) scale(0.94)' : `translate(${side * 16}px, 6px) scale(0.97)`;
+    const origin = from === 'below' ? (rtl ? '0% 100%' : '100% 100%') : side > 0 ? '100% 100%' : '0% 100%';
+    element.animate({ transform: [start, 'none'], transformOrigin: [origin, origin] }, { ...timing, duration: 560, easing: springEasing(0.32) });
+    element.animate({ opacity: [0, 1], filter: ['blur(4px)', 'blur(0px)'] }, { ...timing, duration: 240, easing: 'ease-out' });
+}
+/**
+ * Potrząśnięcie w poziomie - sygnał "nie tak" (pole staje się nieprawidłowe). Krótkie i gasnące,
+ * żeby nie męczyło przy kolejnych próbach; amplituda w px, czas ~0,36 s. Bez WAAPI albo przy
+ * "ogranicz ruch" nic nie robi - stan i tak niesie kolor i komunikat.
+ */
+export function playShakeMotion(element, amplitude = 6) {
+    if (!layoutMotionAllowed())
+        return;
+    const a = amplitude;
+    element.animate({ translate: ['0', `${-a}px 0`, `${a * 0.8}px 0`, `${-a * 0.55}px 0`, `${a * 0.3}px 0`, '0'] }, { id: ANIMATION_ID, duration: 360, easing: 'ease-out' });
+}
+/**
+ * Wskoczenie (pop) - element przysiada i odbija na sprężynie. Odpalane z handlera zmiany, nie z CSS:
+ * reguła na `:checked` zagrałaby też przy pierwszym renderze. `squash` rozciąga element w poziomie
+ * zamiast go zmniejszać (kciuk przełącznika w ruchu). Przy "ogranicz ruch" nic nie robi.
+ */
+export function playPopMotion(element, mode = 'pop') {
+    if (!layoutMotionAllowed())
+        return;
+    const keyframes = mode === 'squash'
+        ? { scale: ['1', '1.3 0.85', '1'] }
+        : { scale: ['0.8', '1'] };
+    element.animate(keyframes, {
+        id: ANIMATION_ID,
+        duration: mode === 'squash' ? 320 : 420,
+        easing: mode === 'squash' ? 'ease-out' : springEasing(0.5),
+    });
+}
+/**
+ * Sygnał błędu kontrolki: pierścień w kolorze błędu rozchodzi się od elementu i gaśnie, a element
+ * krótko się potrząsa (\`shake: false\` - sam pierścień, np. gdy potrząsa już otaczający
+ * \`kpt-form-field\`). Kolor z tokenu \`--kpt-form-field-border-error\` (zapas: \`--kpt-color-danger\`),
+ * więc idzie za motywem. Przy "ogranicz ruch" nic nie robi - błąd i tak niesie kolor ramki.
+ */
+export function playInvalidMotion(element, options = {}) {
+    if (!layoutMotionAllowed())
+        return;
+    const style = getComputedStyle(element);
+    const color = style.getPropertyValue('--kpt-form-field-border-error').trim() ||
+        style.getPropertyValue('--kpt-color-danger').trim() ||
+        'currentColor';
+    element.animate({
+        boxShadow: [
+            `0 0 0 0 color-mix(in srgb, ${color} 55%, transparent)`,
+            `0 0 0 0.45rem color-mix(in srgb, ${color} 0%, transparent)`,
+        ],
+    }, { id: ANIMATION_ID, duration: 560, easing: 'ease-out' });
+    if (options.shake !== false)
+        playShakeMotion(element, 3);
+}
+/**
+ * Wskaźnik wyboru w kontrolce segmentowej: tło aktywnej pozycji (pseudo-element `pseudo`) przejeżdża
+ * z miejsca i szerokości poprzedniej pozycji (`from`, zmierzone przed zmianą) na nową - FLIP samego
+ * pseudo-elementu, bez dodatkowego węzła w DOM. Przy "ogranicz ruch" nic nie robi.
+ */
+export function playIndicatorMotion(from, to, pseudo = '::before') {
+    if (!layoutMotionAllowed())
+        return;
+    const r = to.getBoundingClientRect();
+    if (!r.width || !from.width)
+        return;
+    const dx = from.left - r.left;
+    const sx = from.width / r.width;
+    if (Math.abs(dx) < 0.5 && Math.abs(sx - 1) < 0.01)
+        return;
+    to.animate({ transform: [`translateX(${dx}px) scaleX(${sx})`, 'none'], transformOrigin: ['0 0', '0 0'] }, { id: ANIMATION_ID, duration: 480, easing: springEasing(0.18), pseudoElement: pseudo });
+}

package/dist/flow-diff.d.ts

@@ -0,0 +1,7 @@
+import type { KptFlowChange } from './flow.ts';
+/**
+ * Zmiana listy jako wejście dla `prepareFlowMotion`: indeks usuniętego klucza w starej liście
+ * i dodanego w nowej. Ruch ma sens tylko dla pojedynczej zmiany - przy kilku naraz (np. wyczyszczenie,
+ * podmiana całej wartości) albo przy zmianie kolejności zwraca `null` i lista zmienia się bez ruchu.
+ */
+export declare function flowChangeOf<K>(before: readonly K[], after: readonly K[]): KptFlowChange | null;

package/dist/flow-diff.js

@@ -0,0 +1,17 @@
+/**
+ * Zmiana listy jako wejście dla `prepareFlowMotion`: indeks usuniętego klucza w starej liście
+ * i dodanego w nowej. Ruch ma sens tylko dla pojedynczej zmiany - przy kilku naraz (np. wyczyszczenie,
+ * podmiana całej wartości) albo przy zmianie kolejności zwraca `null` i lista zmienia się bez ruchu.
+ */
+export function flowChangeOf(before, after) {
+    const removed = before.filter((k) => !after.includes(k));
+    const added = after.filter((k) => !before.includes(k));
+    if (removed.length + added.length !== 1)
+        return null;
+    // Wspólne klucze muszą zachować kolejność - inaczej FLIP po indeksach poleciałby z złych miejsc.
+    const keptBefore = before.filter((k) => after.includes(k));
+    const keptAfter = after.filter((k) => before.includes(k));
+    if (keptBefore.some((k, i) => k !== keptAfter[i]))
+        return null;
+    return removed.length ? { removed: before.indexOf(removed[0]) } : { added: after.indexOf(added[0]) };
+}

package/dist/flow.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Ruch listy "płynącej" (tagi w `kpt-chips-input`): elementy w jednym wierszu z zawijaniem, śledzone
+ * po indeksie. Po usunięciu środkowego framework kasuje OSTATNI węzeł i przepisuje treść pozostałych,
+ * więc wejście i wyjście w CSS pokazałyby zły element. Dlatego:
+ * - przed zmianą mierzymy pozycje i - przy usunięciu - klonujemy znikający element (duch),
+ * - po renderze sąsiedzi dosuwają się FLIP-em z pozycji, którą ich dane miały wcześniej,
+ * - duch gaśnie w miejscu, a nowy element wskakuje.
+ * Warstwa DOM bez testów (potrzebuje przeglądarki), wspólna dla obu portów.
+ */
+export interface KptFlowChange {
+    /** Indeks usuniętego elementu w liście PRZED zmianą. */
+    removed?: number;
+    /** Indeks dodanego elementu w liście PO zmianie. */
+    added?: number;
+}
+/**
+ * Zapamiętuje stan listy przed zmianą. Zwraca funkcję do wywołania po wyrenderowaniu nowego stanu
+ * (Angular: `afterNextRender`, React: `useLayoutEffect` - przed malowaniem, inaczej mignie klatka
+ * z nowym układem). `items` to elementy w kolejności, łącznie z tymi za listą (np. pole tekstowe).
+ * `container` musi być pozycjonowany (`position: relative`) - w nim ląduje duch.
+ */
+export declare function prepareFlowMotion(container: HTMLElement, items: readonly HTMLElement[], change: KptFlowChange, motion: 'spring' | 'fade'): (after: readonly HTMLElement[]) => void;

package/dist/flow.js

@@ -0,0 +1,84 @@
+import { layoutMotionAllowed } from "./dom.js";
+import { springEasing } from "./spring.js";
+const FLOW_ID = 'kpt-flow-motion';
+/**
+ * Zapamiętuje stan listy przed zmianą. Zwraca funkcję do wywołania po wyrenderowaniu nowego stanu
+ * (Angular: `afterNextRender`, React: `useLayoutEffect` - przed malowaniem, inaczej mignie klatka
+ * z nowym układem). `items` to elementy w kolejności, łącznie z tymi za listą (np. pole tekstowe).
+ * `container` musi być pozycjonowany (`position: relative`) - w nim ląduje duch.
+ */
+export function prepareFlowMotion(container, items, change, motion) {
+    if (!layoutMotionAllowed())
+        return () => undefined;
+    const origin = container.getBoundingClientRect();
+    const rects = items.map((el) => el.getBoundingClientRect());
+    // Zmierzone razem z trwającym ruchem - teraz można go przerwać, nowy lot ruszy z tego miejsca.
+    for (const el of items)
+        for (const a of el.getAnimations())
+            if (a.id === FLOW_ID)
+                a.cancel();
+    const leaving = change.removed === undefined ? undefined : items[change.removed];
+    const leavingRect = change.removed === undefined ? undefined : rects[change.removed];
+    const ghost = leaving && leavingRect ? makeGhost(leaving, leavingRect, origin, container) : null;
+    return (after) => {
+        if (ghost) {
+            container.appendChild(ghost);
+            const out = motion === 'spring'
+                ? { opacity: [1, 0], transform: ['none', 'scale(0.6)'], filter: ['blur(0px)', 'blur(3px)'] }
+                : { opacity: [1, 0] };
+            ghost
+                .animate(out, { id: FLOW_ID, duration: 220, easing: 'ease-in', fill: 'forwards' })
+                .finished.then(() => ghost.remove(), () => ghost.remove());
+        }
+        const now = container.getBoundingClientRect();
+        after.forEach((el, j) => {
+            if (j === change.added) {
+                playFlowEnter(el, motion);
+                return;
+            }
+            // Indeks, pod którym te same dane stały przed zmianą.
+            let i = j;
+            if (change.removed !== undefined && j >= change.removed)
+                i = j + 1;
+            if (change.added !== undefined && j > change.added)
+                i = j - 1;
+            const before = rects[i];
+            if (!before)
+                return;
+            const r = el.getBoundingClientRect();
+            const dx = before.left - origin.left - (r.left - now.left);
+            const dy = before.top - origin.top - (r.top - now.top);
+            if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5)
+                return;
+            el.animate({ transform: [`translate(${dx}px, ${dy}px)`, 'none'] }, { id: FLOW_ID, duration: motion === 'spring' ? 480 : 240, easing: motion === 'spring' ? springEasing(0.18) : 'ease-out' });
+        });
+    };
+}
+/** Wejście nowego elementu: wskakuje ze zmniejszenia i rozmycia (`fade`: samo przenikanie). */
+function playFlowEnter(el, motion) {
+    if (motion === 'fade') {
+        el.animate({ opacity: [0, 1] }, { id: FLOW_ID, duration: 220, easing: 'ease-out' });
+        return;
+    }
+    el.animate({ transform: ['scale(0.6)', 'none'] }, { id: FLOW_ID, duration: 520, easing: springEasing(0.32) });
+    el.animate({ opacity: [0, 1], filter: ['blur(3px)', 'blur(0px)'] }, { id: FLOW_ID, duration: 200, easing: 'ease-out' });
+}
+/** Nieinteraktywny klon w miejscu znikającego elementu, wewnątrz `container`. */
+function makeGhost(source, rect, origin, container) {
+    const ghost = source.cloneNode(true);
+    for (const node of [ghost, ...ghost.querySelectorAll('[id]')])
+        node.removeAttribute('id');
+    ghost.removeAttribute('role');
+    ghost.setAttribute('aria-hidden', 'true');
+    ghost.inert = true;
+    Object.assign(ghost.style, {
+        position: 'absolute',
+        left: `${rect.left - origin.left - container.clientLeft}px`,
+        top: `${rect.top - origin.top - container.clientTop}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+        margin: '0',
+        pointerEvents: 'none',
+    });
+    return ghost;
+}