@konce-pt/motion 0.0.0-stage → 0.14.0

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { springProgress, springEasing } from './spring.ts';
+export { planLayoutMotion, layoutMotionDuration } from './layout.ts';
+export type { KptLayoutMotion, KptRect, KptLayoutFrame, KptLayoutInnerFrame, KptLayoutFlight, KptLayoutPlanOptions, } from './layout.ts';
+export { layoutMotionAllowed, layoutMorphSupported, snapshotLayout, stopLayoutMotion, playLayoutMotion, morphLayout, } from './dom.ts';
+export type { KptLayoutSnapshot, KptPlayLayoutOptions } from './dom.ts';
+export { applyMotionConfig, playEnterMotion, playShakeMotion, playPopMotion, playInvalidMotion, playIndicatorMotion, } from './dom.ts';
+export type { KptEnterFrom } from './dom.ts';
+export { resolveLayoutMotion, resolveCollapseMotion, resolveEnterMotion, resolveToggleMotion, KPT_DEFAULT_TOGGLE_MOTION, KPT_DEFAULT_ENTER_MOTION, motionRootStyle, KPT_DEFAULT_LAYOUT_MOTION, KPT_DEFAULT_COLLAPSE_MOTION, } from './config.ts';
+export type { KptMotionConfig, KptMotionRootStyle, KptCollapseMotion, KptEnterMotion, KptToggleMotion } from './config.ts';
+export { snapshotKeyed, playKeyedMotion, stopKeyedMotion, morphKeyed, isVisibleInScroller, revealInScroller, } from './keyed.ts';
+export type { KptKeyedNode, KptKeyedSnapshot, KptKeyedClasses, KptKeyedMotionOptions } from './keyed.ts';
+export { prepareFlowMotion } from './flow.ts';
+export type { KptFlowChange } from './flow.ts';
+export { flowChangeOf } from './flow-diff.ts';
+export { stepperSchedule, stepperScheduleOptions } from './stepper.ts';
+export type { KptStepperSchedule, KptStepperScheduleOptions, KptStepTiming } from './stepper.ts';
+export { preparePanelSwap } from './swap.ts';
+export { playStepperLight } from './stepper-dom.ts';
+export { KPT_LOADER_VARIANTS, LOADER_PALETTE, LOADER_VIEWBOX, LOADER_RESULT_MS, LOADER_QUIET_MS, cubicBezier, loaderProgress, loaderColor, loaderOnColor, loaderSubtle, loaderPalette, } from './loader.ts';
+export type { KptLoaderVariant, KptLoaderStatus, KptLoaderResult, KptLoaderRole, KptLoaderColor } from './loader.ts';
+export { createLoader, swapText, setText } from './loader-dom.ts';
+export type { KptLoaderOptions, KptLoaderController } from './loader-dom.ts';

package/dist/index.js

@@ -0,0 +1,13 @@
+export { springProgress, springEasing } from "./spring.js";
+export { planLayoutMotion, layoutMotionDuration } from "./layout.js";
+export { layoutMotionAllowed, layoutMorphSupported, snapshotLayout, stopLayoutMotion, playLayoutMotion, morphLayout, } from "./dom.js";
+export { applyMotionConfig, playEnterMotion, playShakeMotion, playPopMotion, playInvalidMotion, playIndicatorMotion, } from "./dom.js";
+export { resolveLayoutMotion, resolveCollapseMotion, resolveEnterMotion, resolveToggleMotion, KPT_DEFAULT_TOGGLE_MOTION, KPT_DEFAULT_ENTER_MOTION, motionRootStyle, KPT_DEFAULT_LAYOUT_MOTION, KPT_DEFAULT_COLLAPSE_MOTION, } from "./config.js";
+export { snapshotKeyed, playKeyedMotion, stopKeyedMotion, morphKeyed, isVisibleInScroller, revealInScroller, } from "./keyed.js";
+export { prepareFlowMotion } from "./flow.js";
+export { flowChangeOf } from "./flow-diff.js";
+export { stepperSchedule, stepperScheduleOptions } from "./stepper.js";
+export { preparePanelSwap } from "./swap.js";
+export { playStepperLight } from "./stepper-dom.js";
+export { KPT_LOADER_VARIANTS, LOADER_PALETTE, LOADER_VIEWBOX, LOADER_RESULT_MS, LOADER_QUIET_MS, cubicBezier, loaderProgress, loaderColor, loaderOnColor, loaderSubtle, loaderPalette, } from "./loader.js";
+export { createLoader, swapText, setText } from "./loader-dom.js";

package/dist/keyed.d.ts

@@ -0,0 +1,64 @@
+import { type KptRect } from './layout.ts';
+/**
+ * Ruch list z kluczem - elementy rozpoznawane po danych, nie po pozycji w DOM. Komponenty śledzą
+ * wiersze po indeksie, więc po przeniesieniu ten sam `<li>` pokazuje już inny element; dlatego
+ * stan przed zmianą zapamiętujemy pod kluczem (referencją elementu danych), a po renderze
+ * szukamy węzła, który ten klucz pokazuje.
+ *
+ * Przeskok między dwoma przewijanymi pojemnikami (np. dwa panele `kpt-pick-list`) leci jako
+ * duch - klon w warstwie nad całym komponentem - bo prawdziwy wiersz przyciąłby `overflow`
+ * panelu. Przesunięcia wewnątrz jednego pojemnika to zwykły FLIP prawdziwych węzłów.
+ */
+/** Węzeł listy i klucz elementu danych, który pokazuje. */
+export interface KptKeyedNode<K> {
+    key: K;
+    element: HTMLElement;
+}
+interface KeyedEntry {
+    rect: KptRect;
+    visible: boolean;
+    scroller: HTMLElement | null;
+}
+/** Stan list przed zmianą: prostokąt (względem korzenia), widoczność i pojemnik pod kluczem. */
+export type KptKeyedSnapshot<K> = Map<K, KeyedEntry>;
+export interface KptKeyedClasses {
+    /** Klon lecący między pojemnikami. */
+    ghostClass: string;
+    /** Prawdziwy węzeł czekający, aż duch wyląduje. */
+    hiddenClass: string;
+    /** Węzeł przesuwany wewnątrz pojemnika (np. `position: relative; z-index`). */
+    movingClass: string;
+}
+export interface KptKeyedMotionOptions extends KptKeyedClasses {
+    /** Ruch duchów między pojemnikami; przesunięcia wewnątrz pojemnika są zawsze sprężyną. */
+    motion: 'spring' | 'arc';
+    /** Przewijany pojemnik węzła - widoczność i przeskok liczymy względem niego. */
+    scrollerOf: (element: HTMLElement) => HTMLElement | null;
+    /**
+     * Klucze elementów przestawianych przez użytkownika (główna akcja) w obrębie pojemnika - lecą
+     * w materiale `motion` i nad sąsiadami; reszta robi im miejsce spokojną sprężyną.
+     */
+    lead?: ReadonlySet<unknown>;
+}
+/** Czy węzeł jest widoczny w swoim przewijanym pojemniku (choćby częściowo). */
+export declare function isVisibleInScroller(element: HTMLElement, scroller: HTMLElement | null): boolean;
+/** Przewija pojemnik tak, żeby węzeł był w nim widoczny (bez przewijania strony). */
+export declare function revealInScroller(element: HTMLElement, scroller: HTMLElement | null): void;
+/** Mierzy węzły przed zmianą. Węzeł czekający na ducha bierze pozycję ducha z ekranu. */
+export declare function snapshotKeyed<K>(root: HTMLElement, nodes: readonly KptKeyedNode<K>[], scrollerOf: (element: HTMLElement) => HTMLElement | null): KptKeyedSnapshot<K>;
+/** Przerywa trwający ruch: animacje, duchy i klasy stanu. Wołać PO pomiarze. */
+export declare function stopKeyedMotion(root: HTMLElement, classes: KptKeyedClasses): void;
+/**
+ * Gra ruch od `first` do bieżącego (wyrenderowanego) stanu list. Węzeł, który zmienił pojemnik,
+ * leci jako duch (gdy był widoczny przed i jest widoczny po); węzeł w tym samym pojemniku
+ * przesuwa się sam. Klucze nieznane w `first` (nowe dane) się nie ruszają. Zwraca czas w ms.
+ */
+export declare function playKeyedMotion<K>(root: HTMLElement, first: KptKeyedSnapshot<K>, nodes: readonly KptKeyedNode<K>[], options: KptKeyedMotionOptions, originEl?: Element | null): number;
+/**
+ * Natywny morf (View Transitions) list z kluczem. Nazwy idą za danymi: przed zmianą dostają je
+ * węzły pokazujące dany klucz, w środku przejścia - po `update()` - węzły, które pokazują go
+ * teraz. Przejście rysuje się nad stroną, więc `overflow` paneli go nie przycina. `include`
+ * zawęża nazwy do widocznych węzłów (przewinięte poza panel nie mają skąd i dokąd lecieć).
+ */
+export declare function morphKeyed<K>(before: readonly KptKeyedNode<K>[], after: () => readonly KptKeyedNode<K>[], namePrefix: string, className: string, update: () => void, include?: (element: HTMLElement) => boolean): void;
+export {};

package/dist/keyed.js

@@ -0,0 +1,221 @@
+import { layoutMorphSupported } from "./dom.js";
+import { layoutMotionDuration, planLayoutMotion } from "./layout.js";
+const ANIMATION_ID = 'kpt-keyed-motion';
+/** Duch w locie dla prawdziwego węzła - przerwany lot startuje od miejsca ducha na ekranie. */
+const ghostOf = new WeakMap();
+/** Czy węzeł jest widoczny w swoim przewijanym pojemniku (choćby częściowo). */
+export function isVisibleInScroller(element, scroller) {
+    return intersects(element.getBoundingClientRect(), scroller);
+}
+/** Przewija pojemnik tak, żeby węzeł był w nim widoczny (bez przewijania strony). */
+export function revealInScroller(element, scroller) {
+    if (!scroller)
+        return;
+    const s = scroller.getBoundingClientRect();
+    const r = element.getBoundingClientRect();
+    if (r.bottom > s.bottom)
+        scroller.scrollTop += r.bottom - s.bottom;
+    else if (r.top < s.top)
+        scroller.scrollTop -= s.top - r.top;
+}
+/** Mierzy węzły przed zmianą. Węzeł czekający na ducha bierze pozycję ducha z ekranu. */
+export function snapshotKeyed(root, nodes, scrollerOf) {
+    const box = root.getBoundingClientRect();
+    const map = new Map();
+    for (const { key, element } of nodes) {
+        if (map.has(key))
+            continue;
+        const ghost = ghostOf.get(element);
+        const live = ghost?.isConnected ? ghost : element;
+        const scroller = scrollerOf(element);
+        const r = live.getBoundingClientRect();
+        map.set(key, { rect: relative(r, box), visible: live !== element || intersects(r, scroller), scroller });
+    }
+    return map;
+}
+/** Przerywa trwający ruch: animacje, duchy i klasy stanu. Wołać PO pomiarze. */
+export function stopKeyedMotion(root, classes) {
+    for (const a of root.getAnimations({ subtree: true }))
+        if (a.id === ANIMATION_ID)
+            a.cancel();
+    for (const ghost of root.querySelectorAll(`.${classes.ghostClass}`))
+        ghost.remove();
+    for (const el of root.querySelectorAll(`.${classes.hiddenClass}, .${classes.movingClass}`)) {
+        el.classList.remove(classes.hiddenClass, classes.movingClass);
+        el.style.zIndex = '';
+    }
+}
+/**
+ * Gra ruch od `first` do bieżącego (wyrenderowanego) stanu list. Węzeł, który zmienił pojemnik,
+ * leci jako duch (gdy był widoczny przed i jest widoczny po); węzeł w tym samym pojemniku
+ * przesuwa się sam. Klucze nieznane w `first` (nowe dane) się nie ruszają. Zwraca czas w ms.
+ */
+export function playKeyedMotion(root, first, nodes, options, originEl) {
+    const box = root.getBoundingClientRect();
+    const direct = [];
+    const leads = [];
+    const ghosts = [];
+    const seen = new Set();
+    for (const { key, element } of nodes) {
+        const before = first.get(key);
+        if (!before || seen.has(key))
+            continue;
+        seen.add(key);
+        const scroller = options.scrollerOf(element);
+        const r = element.getBoundingClientRect();
+        const move = { element, from: before.rect, to: relative(r, box) };
+        if (before.scroller !== scroller) {
+            if (before.visible && intersects(r, scroller))
+                ghosts.push(move);
+        }
+        else if (before.visible || intersects(r, scroller)) {
+            (options.lead?.has(key) ? leads : direct).push(move);
+        }
+    }
+    const sample = nodes[0]?.element;
+    const radius = sample ? Number.parseFloat(getComputedStyle(sample).borderTopLeftRadius) || 0 : 0;
+    const scrim = getComputedStyle(root).getPropertyValue('--kpt-color-overlay-scrim').trim();
+    let origin;
+    if (originEl) {
+        const o = originEl.getBoundingClientRect();
+        origin = { x: o.left - box.left + o.width / 2, y: o.top - box.top + o.height / 2 };
+    }
+    // Wtórny ruch: sąsiedzi domykają lukę i robią miejsce - zawsze spokojna sprężyna.
+    const directFlights = planLayoutMotion(direct.map((m) => m.from), direct.map((m) => m.to), { motion: 'spring', resize: false, radius, stagger: 12 });
+    for (const flight of directFlights) {
+        const move = direct[flight.index];
+        if (!move)
+            continue;
+        move.element.classList.add(options.movingClass);
+        const anim = move.element.animate(frames(flight), timing(flight));
+        anim.finished.then(() => {
+            if (!move.element.getAnimations().some((a) => a.id === ANIMATION_ID && a.playState === 'running')) {
+                move.element.classList.remove(options.movingClass);
+            }
+        }, () => undefined);
+    }
+    // Główna akcja w pojemniku: przestawiany element leci w wybranym materiale, nad sąsiadami.
+    const shadowColor = scrim ? { shadowColor: `color-mix(in srgb, ${scrim} 55%, transparent)` } : {};
+    const leadFlights = planLayoutMotion(leads.map((m) => m.from), leads.map((m) => m.to), { motion: options.motion, resize: false, radius, ...(origin ? { origin } : {}), ...shadowColor });
+    for (const flight of leadFlights) {
+        const move = leads[flight.index];
+        if (!move)
+            continue;
+        move.element.classList.add(options.movingClass);
+        move.element.style.zIndex = '2';
+        const land = () => {
+            if (move.element.getAnimations().some((a) => a.id === ANIMATION_ID && a.playState === 'running'))
+                return;
+            move.element.classList.remove(options.movingClass);
+            move.element.style.zIndex = '';
+        };
+        move.element.animate(frames(flight), timing(flight)).finished.then(land, land);
+    }
+    // Główna akcja między pojemnikami: duchy lecą w wybranym materiale.
+    const ghostFlights = planLayoutMotion(ghosts.map((m) => m.from), ghosts.map((m) => m.to), {
+        motion: options.motion,
+        resize: false,
+        radius,
+        stagger: 40,
+        ...(origin ? { origin } : {}),
+        ...shadowColor,
+    });
+    for (const flight of ghostFlights) {
+        const move = ghosts[flight.index];
+        if (!move)
+            continue;
+        const ghost = makeGhost(move.element, move.to, options);
+        root.appendChild(ghost);
+        ghostOf.set(move.element, ghost);
+        move.element.classList.add(options.hiddenClass);
+        const land = () => {
+            ghost.remove();
+            if (ghostOf.get(move.element) === ghost) {
+                ghostOf.delete(move.element);
+                move.element.classList.remove(options.hiddenClass);
+            }
+        };
+        ghost.animate(frames(flight), timing(flight)).finished.then(land, land);
+    }
+    return Math.max(layoutMotionDuration(directFlights), layoutMotionDuration(leadFlights), layoutMotionDuration(ghostFlights));
+}
+/**
+ * Natywny morf (View Transitions) list z kluczem. Nazwy idą za danymi: przed zmianą dostają je
+ * węzły pokazujące dany klucz, w środku przejścia - po `update()` - węzły, które pokazują go
+ * teraz. Przejście rysuje się nad stroną, więc `overflow` paneli go nie przycina. `include`
+ * zawęża nazwy do widocznych węzłów (przewinięte poza panel nie mają skąd i dokąd lecieć).
+ */
+export function morphKeyed(before, after, namePrefix, className, update, include = () => true) {
+    if (!layoutMorphSupported()) {
+        update();
+        return;
+    }
+    const ids = new Map();
+    const named = [];
+    const name = (element, id) => {
+        element.style.viewTransitionName = id;
+        element.style.viewTransitionClass = className;
+        named.push(element);
+    };
+    const clear = () => {
+        for (const el of named.splice(0)) {
+            el.style.viewTransitionName = '';
+            el.style.viewTransitionClass = '';
+        }
+    };
+    before.forEach(({ key, element }, i) => {
+        if (ids.has(key) || !include(element))
+            return;
+        const id = `${namePrefix}-${i}`;
+        ids.set(key, id);
+        name(element, id);
+    });
+    document
+        .startViewTransition(() => {
+        clear();
+        update();
+        const used = new Set();
+        for (const { key, element } of after()) {
+            const id = ids.get(key);
+            if (!id || used.has(id) || !include(element))
+                continue;
+            used.add(id);
+            name(element, id);
+        }
+    })
+        .finished.then(clear, clear);
+}
+function makeGhost(source, at, options) {
+    const ghost = source.cloneNode(true);
+    for (const attr of ['id', 'role', 'tabindex', 'aria-selected', 'aria-label', 'draggable'])
+        ghost.removeAttribute(attr);
+    ghost.setAttribute('aria-hidden', 'true');
+    ghost.classList.remove(options.hiddenClass, options.movingClass);
+    ghost.classList.add(options.ghostClass);
+    Object.assign(ghost.style, {
+        position: 'absolute',
+        left: `${at.x}px`,
+        top: `${at.y}px`,
+        width: `${at.width}px`,
+        height: `${at.height}px`,
+        margin: '0',
+        boxSizing: 'border-box',
+        pointerEvents: 'none',
+    });
+    return ghost;
+}
+function frames(flight) {
+    return flight.item.map((f) => ({ ...f }));
+}
+function timing(flight) {
+    return { id: ANIMATION_ID, duration: flight.duration, delay: flight.delay, easing: 'linear', fill: 'backwards' };
+}
+function relative(r, box) {
+    return { x: r.left - box.left, y: r.top - box.top, width: r.width, height: r.height };
+}
+function intersects(r, scroller) {
+    if (!scroller)
+        return true;
+    const s = scroller.getBoundingClientRect();
+    return r.bottom > s.top + 1 && r.top < s.bottom - 1 && r.right > s.left && r.left < s.right;
+}

package/dist/layout.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Styl ruchu przy zmianie układu: bez ruchu, sprężyna, lot po łuku z głębią albo natywny morf
+ * przeglądarki (View Transitions). Klatki liczy ten moduł tylko dla `spring` i `arc` - morf
+ * robi przeglądarka ze zrzutów starego i nowego stanu.
+ */
+export type KptLayoutMotion = 'none' | 'spring' | 'arc' | 'morph';
+/** Prostokąt elementu względem wspólnego kontenera (lewy górny róg + rozmiar). */
+export interface KptRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Klatka elementu: przesunięcie i skala względem pozycji końcowej oraz wyrównany promień rogu. */
+export interface KptLayoutFrame {
+    transform: string;
+    borderRadius: string;
+    boxShadow?: string;
+}
+/** Klatka wnętrza: odwrotność skali elementu, żeby treść się nie rozciągała. */
+export interface KptLayoutInnerFrame {
+    transform: string;
+}
+/** Lot jednego elementu - gotowe tablice klatek do `element.animate(frames, { easing: 'linear' })`. */
+export interface KptLayoutFlight {
+    /** Indeks elementu w tablicach `first` / `last`. */
+    index: number;
+    delay: number;
+    duration: number;
+    item: KptLayoutFrame[];
+    inner: KptLayoutInnerFrame[];
+}
+export interface KptLayoutPlanOptions {
+    motion: 'spring' | 'arc';
+    /** Promień rogu elementu w px - wyrównywany co klatkę, żeby skala go nie spłaszczyła. */
+    radius?: number;
+    /** Skąd rusza fala w `arc` (zwykle środek klikniętego przycisku); domyślnie prawy górny róg. */
+    origin?: {
+        x: number;
+        y: number;
+    };
+    /** Kolor cienia unoszonej karty w `arc`; bez niego cienia nie ma. */
+    shadowColor?: string;
+    /** Liczba klatek na lot (domyślnie 36 - przy `linear` między nimi to wystarcza na 60 kl./s). */
+    frames?: number;
+    /**
+     * `false` - lot tylko przesuwa, bez zmiany rozmiaru (wiersze listy, które mają tę samą
+     * szerokość po obu stronach; bez wrappera do kontr-skali tekst rozciągałby się o piksel).
+     */
+    resize?: boolean;
+    /** Kaskada `spring` w ms na element (domyślnie 22); całość przycięta do 300 ms. */
+    stagger?: number;
+}
+/**
+ * Plan FLIP dla zmiany układu: z prostokątów przed zmianą (`first`, najlepiej zmierzonych
+ * z ekranu, razem z trwającym transformem - wtedy przerwany ruch zaczyna od miejsca, w którym
+ * element jest widoczny) i po zmianie (`last`, bez transformów) liczy klatki elementu i jego
+ * wnętrza. Element gra od starej pozycji do `transform: none`; wnętrze dostaje odwrotną skalę.
+ *
+ * `transform-origin` obu musi być `0 0`: skala względem środka pokazywałaby w pierwszych
+ * klatkach środek treści - przy przejściu siatka -> lista to pusty pas między nazwą a ceną.
+ */
+export declare function planLayoutMotion(first: readonly KptRect[], last: readonly KptRect[], options: KptLayoutPlanOptions): KptLayoutFlight[];
+/** Ile trwa cały plan - do zdjęcia stanu "w ruchu" bez czekania na każdą obietnicę. */
+export declare function layoutMotionDuration(flights: readonly KptLayoutFlight[]): number;

package/dist/layout.js

@@ -0,0 +1,115 @@
+import { round, springProgress } from "./spring.js";
+/** Element, który się nie ruszył (poniżej pół piksela), nie dostaje lotu. */
+const STILL = 0.5;
+const SPRING = springProgress(0.32);
+const SOFT = springProgress(0.18);
+/**
+ * Plan FLIP dla zmiany układu: z prostokątów przed zmianą (`first`, najlepiej zmierzonych
+ * z ekranu, razem z trwającym transformem - wtedy przerwany ruch zaczyna od miejsca, w którym
+ * element jest widoczny) i po zmianie (`last`, bez transformów) liczy klatki elementu i jego
+ * wnętrza. Element gra od starej pozycji do `transform: none`; wnętrze dostaje odwrotną skalę.
+ *
+ * `transform-origin` obu musi być `0 0`: skala względem środka pokazywałaby w pierwszych
+ * klatkach środek treści - przy przejściu siatka -> lista to pusty pas między nazwą a ceną.
+ */
+export function planLayoutMotion(first, last, options) {
+    const count = Math.min(first.length, last.length);
+    const frames = Math.max(2, Math.round(options.frames ?? 36));
+    const origin = options.origin ?? { x: Math.max(0, ...last.map((r) => r.x + r.width)), y: 0 };
+    const flights = [];
+    for (let i = 0; i < count; i++) {
+        const f = first[i];
+        const l = last[i];
+        if (!f || !l || l.width <= 0 || l.height <= 0 || isStill(f, l))
+            continue;
+        const from = options.resize === false ? { ...f, width: l.width, height: l.height } : f;
+        const course = options.motion === 'spring' ? springCourse(i, from, l, options.stagger ?? 22) : arcCourse(from, l, origin);
+        flights.push({ index: i, ...sample(course, frames, options), delay: Math.round(course.delay), duration: course.duration });
+    }
+    return flights;
+}
+/** Sprężyna po prostej z lekką kaskadą od pierwszego elementu. */
+function springCourse(i, f, l, stagger) {
+    const dx = f.x - l.x;
+    const dy = f.y - l.y;
+    const fsx = f.width / l.width;
+    const fsy = f.height / l.height;
+    return {
+        delay: Math.min(300, i * stagger),
+        duration: 640,
+        state: (q) => {
+            const p = SPRING(q);
+            return { x: dx * (1 - p), y: dy * (1 - p), sx: lerp(fsx, 1, p), sy: lerp(fsy, 1, p), rotate: 0, lift: 0 };
+        },
+    };
+}
+/**
+ * Lot po łuku: karta unosi się (lekkie powiększenie, cień), leci łukiem z przechyłem w stronę
+ * ruchu i ląduje na miękkiej sprężynie. Fala startuje od `origin` - bliższe karty ruszają pierwsze.
+ */
+function arcCourse(f, l, origin) {
+    const dx = f.x - l.x;
+    const dy = f.y - l.y;
+    const fsx = f.width / l.width;
+    const fsy = f.height / l.height;
+    const dist = Math.hypot(f.x + f.width / 2 - origin.x, f.y + f.height / 2 - origin.y);
+    const arc = Math.min(46, 12 + Math.hypot(dx, dy) * 0.12);
+    const tilt = clamp(-dx / 55, -7, 7);
+    return {
+        delay: Math.min(300, dist * 0.55),
+        duration: 780,
+        state: (q) => {
+            const p = SOFT(q);
+            const lift = Math.sin(Math.PI * Math.min(1, q * 1.25));
+            const m = 1 + 0.05 * lift;
+            return { x: dx * (1 - p), y: dy * (1 - p) - arc * lift, sx: lerp(fsx, 1, p) * m, sy: lerp(fsy, 1, p) * m, rotate: tilt * lift, lift };
+        },
+    };
+}
+/** Próbkuje stan lotu do klatek elementu i wnętrza; ostatnia klatka trafia dokładnie w cel. */
+function sample(course, frames, options) {
+    const radius = options.radius ?? 0;
+    const shadowColor = options.motion === 'arc' ? options.shadowColor : undefined;
+    const item = [];
+    const inner = [];
+    for (let k = 0; k < frames; k++) {
+        const s = course.state(k / frames);
+        const sx = Math.max(0.02, s.sx);
+        const sy = Math.max(0.02, s.sy);
+        const frame = {
+            transform: `translate(${round(s.x, 2)}px, ${round(s.y, 2)}px) rotate(${round(s.rotate, 2)}deg) scale(${round(sx, 4)}, ${round(sy, 4)})`,
+            borderRadius: `${round(radius / sx, 2)}px / ${round(radius / sy, 2)}px`,
+        };
+        if (shadowColor)
+            frame.boxShadow = shadow(s.lift, shadowColor);
+        item.push(frame);
+        inner.push({ transform: `scale(${round(1 / sx, 4)}, ${round(1 / sy, 4)})` });
+    }
+    // Ostatnia klatka dokładnie w celu - inaczej po animacji zostałby ślad zaokrągleń.
+    const end = { transform: 'none', borderRadius: `${radius}px` };
+    if (shadowColor)
+        end.boxShadow = 'none';
+    item.push(end);
+    inner.push({ transform: 'none' });
+    return { item, inner };
+}
+/** Ile trwa cały plan - do zdjęcia stanu "w ruchu" bez czekania na każdą obietnicę. */
+export function layoutMotionDuration(flights) {
+    return flights.reduce((max, f) => Math.max(max, f.delay + f.duration), 0);
+}
+function isStill(a, b) {
+    return (Math.abs(a.x - b.x) < STILL &&
+        Math.abs(a.y - b.y) < STILL &&
+        Math.abs(a.width - b.width) < STILL &&
+        Math.abs(a.height - b.height) < STILL);
+}
+function shadow(lift, color) {
+    const k = Math.max(0, Math.min(1, lift));
+    return `0 ${round(4 + 22 * k, 1)}px ${round(10 + 34 * k, 1)}px -10px ${color}`;
+}
+function lerp(a, b, p) {
+    return a + (b - a) * p;
+}
+function clamp(v, lo, hi) {
+    return Math.max(lo, Math.min(hi, v));
+}

package/dist/loader-dom.d.ts

@@ -0,0 +1,48 @@
+import { type KptLoaderColor, type KptLoaderResult, type KptLoaderStatus, type KptLoaderVariant } from './loader.ts';
+/**
+ * Warstwa DOM `kpt-loader` - wspólna dla obu portów, bo budowa rysunku, zegar i choreografia
+ * wyniku są w Angularze i Reakcie identyczne. Komponent renderuje pusty element sceny, a ten
+ * moduł wkłada do niego SVG i gra go w jednej pętli `requestAnimationFrame`.
+ *
+ * Wszystko, co się rusza, chodzi na własnym zegarze loadera (timery i przejścia też), nie na
+ * WAAPI: `speed` przyspiesza pętlę w całości, loader poza ekranem stoi razem ze swoim czasem,
+ * a wynik da się przewinąć do końca w jednej chwili (loader, który od razu ma `success`).
+ * Bez testów jednostkowych - potrzebuje przeglądarki; liczby siedzą w `loader.ts`.
+ */
+export interface KptLoaderOptions {
+    variant: KptLoaderVariant;
+    status: KptLoaderStatus;
+    /** Postęp 0..1 albo `null` (nieokreślony). Rysują go `ring` i `wave`. */
+    progress: number | null;
+    /** Barwy pętli (rola motywu albo kolor CSS); `null` = paleta wariantu. */
+    colors: readonly KptLoaderColor[] | null;
+    successColor: KptLoaderColor;
+    errorColor: KptLoaderColor;
+    /** Napis w kapsule wyniku (`bridge`); zmiana w trakcie przepisuje go na miejscu. */
+    successText: string;
+    errorText: string;
+    /** Mnożnik tempa pętli (wynik zawsze w swoim czasie). */
+    speed: number;
+    /** Ruch wyłączony konfiguracją - pętla zwalnia, wynik bez choreografii. */
+    reduced: boolean;
+    /** Koniec choreografii wyniku. Nie przychodzi, gdy loader od razu ma wynik. */
+    onSettled?: (result: KptLoaderResult) => void;
+}
+export interface KptLoaderController {
+    update(next: Partial<KptLoaderOptions>): void;
+    destroy(): void;
+}
+/**
+ * Wkłada loader do `stage` i zaczyna grać. `content` to element z treścią komponentu (ikona
+ * w środku pierścienia) - moduł tylko go skaluje, nigdy nie zmienia jego dzieci.
+ */
+export declare function createLoader(stage: HTMLElement, content: HTMLElement | null, options: KptLoaderOptions): KptLoaderController;
+/**
+ * Podmienia napis w `box` z przenikaniem: stary odpływa w górę i rozmywa się, nowy wchodzi z dołu.
+ * Pudełko musi trzymać dzieci w jednej komórce siatki (np. `.kpt-update__swap`), żeby na chwilę
+ * leżały na sobie. Stary napis od razu dostaje `aria-hidden`. Bez ruchu (`motion: false` albo
+ * systemowe "ogranicz ruch") napis zmienia się od razu.
+ */
+export declare function swapText(box: HTMLElement, text: string, motion?: boolean): void;
+/** Zmienia bieżący napis `box` bez przenikania - licznik bajtów w trakcie pobierania. */
+export declare function setText(box: HTMLElement, text: string): void;