@konce-pt/motion 0.16.1 → 0.18.0

package/README.md

@@ -1,12 +1,14 @@
 <p align="center">
-  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI - Angular component library" width="100%" />
+  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI" width="100%" />
 </p>
 
 # @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.
+odgrywa - a także rdzeń `kpt-loader` (sześć wariantów), lot podglądu zdjęcia `kpt-image` i przesuw
+z paskiem miniatur `kpt-galleria`. 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).
@@ -34,7 +36,8 @@ const flights = planLayoutMotion(before, after, { motion: 'spring', radius: 8 })
 
 `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:
+(`spring | fade | none`). Funkcje `resolve*Motion(input, config)` (`resolveCollapseMotion` ma trzeci
+argument `animated` - dawny wyłącznik komponentu) 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.
@@ -42,19 +45,31 @@ komponentów - `layout` (`spring | arc | morph | none`), `collapse`, `enter` i `
 ## API
 
 - **Konfiguracja** - `resolveLayoutMotion`, `resolveCollapseMotion`, `resolveEnterMotion`, `resolveToggleMotion`,
-  `motionRootStyle`, stałe `KPT_DEFAULT_*_MOTION`, typy `KptMotionConfig`, `KptLayoutMotion`,
-  `KptCollapseMotion`, `KptEnterMotion`, `KptToggleMotion`
+  `motionRootStyle`, stałe `KPT_DEFAULT_*_MOTION`, typy `KptMotionConfig`, `KptMotionRootStyle`,
+  `KptLayoutMotion`, `KptCollapseMotion`, `KptEnterMotion`, `KptToggleMotion`
 - **Sprężyny** - `springProgress`, `springEasing`
-- **Loty układu** - `planLayoutMotion`, `layoutMotionDuration`, typy `KptRect`, `KptLayoutFlight`
+- **Loty układu** - `planLayoutMotion`, `layoutMotionDuration`, typy `KptRect`, `KptLayoutFlight`,
+  `KptLayoutFrame`, `KptLayoutInnerFrame`, `KptLayoutPlanOptions`
 - **Warstwa DOM** - `snapshotLayout`, `playLayoutMotion`, `stopLayoutMotion`, `morphLayout`,
-  `applyMotionConfig`, `layoutMotionAllowed`, `layoutMorphSupported`
+  `applyMotionConfig`, `layoutMotionAllowed`, `layoutMorphSupported`, typy `KptLayoutSnapshot`,
+  `KptPlayLayoutOptions`
 - **Mikroruch** - `playEnterMotion`, `playShakeMotion`, `playPopMotion`, `playInvalidMotion`,
-  `playIndicatorMotion`
+  `playIndicatorMotion`, typ `KptEnterFrom`
 - **Listy z kluczem** - `snapshotKeyed`, `playKeyedMotion`, `stopKeyedMotion`, `morphKeyed`,
-  `isVisibleInScroller`, `revealInScroller`
+  `isVisibleInScroller`, `revealInScroller`, typy `KptKeyedNode`, `KptKeyedSnapshot`, `KptKeyedClasses`,
+  `KptKeyedMotionOptions`
 - **Zawijany wiersz (tagi, chipy)** - `prepareFlowMotion`, `flowChangeOf`, typ `KptFlowChange`
 - **Kreator i podmiana treści** - `stepperSchedule`, `stepperScheduleOptions`, `playStepperLight`, `preparePanelSwap`, typy
-  `KptStepperSchedule`, `KptStepTiming`
+  `KptStepperSchedule`, `KptStepperScheduleOptions`, `KptStepTiming`
+- **Podgląd zdjęcia (`kpt-image`)** - `zoomFlight`, `playZoomOpen`, `playZoomClose`, `stopZoomMotion`,
+  stałe `KPT_ZOOM_*_MS`, typy `KptZoomFlight`, `KptZoomElements`
+- **Galeria (`kpt-galleria`)** - `gallerySlide`, `revealDelta`, `stripEdges`, `inertiaStep`,
+  `playGallerySlide`, `stopGallerySlide`, `revealThumb`, `scrollStrip`, `trackStripEdges`,
+  `attachDragScroll`, stałe `KPT_GALLERY_*`, `KPT_INERTIA_STOP`, typy `KptGallerySlide`,
+  `KptGallerySlideOptions`
+- **Loader (`kpt-loader`)** - `createLoader`, `loaderProgress`, `loaderPalette`, `loaderColor`,
+  `loaderOnColor`, `loaderSubtle`, `cubicBezier`, `swapText`, `setText`, stałe `KPT_LOADER_VARIANTS`,
+  `LOADER_*`, typy `KptLoader*`
 
 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).

package/dist/config.d.ts

@@ -32,7 +32,7 @@ export interface KptMotionConfig {
     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`. */
+    /** Domyślny ruch pojawiania się (czat: wiadomości, reakcje, status, dock; podgląd `kpt-image`, przesuw `kpt-galleria`). Domyślnie `spring`. */
     enter?: KptEnterMotion;
     /** Domyślny ruch przełączania (checkbox, radio, switch). Domyślnie `spring`. */
     toggle?: KptToggleMotion;

package/dist/gallery-dom.d.ts

@@ -0,0 +1,47 @@
+import type { KptEnterMotion } from './config.ts';
+export interface KptGallerySlideOptions {
+    /** Scena - pojemnik z `overflow: hidden`, w którym leży zdjęcie. */
+    readonly stage: HTMLElement;
+    /** Zdjęcie główne, już z nowym `src`. */
+    readonly image: HTMLImageElement;
+    /** `src` poprzedniego zdjęcia - z niego powstaje duch, który się cofa. */
+    readonly previousSrc: string;
+    /** 1 = następne, -1 = poprzednie. */
+    readonly direction: 1 | -1;
+    readonly motion: KptEnterMotion;
+}
+/**
+ * Zmiana zdjęcia w galerii. Wołać po renderze, gdy zdjęcie główne ma już nowy `src`.
+ * `spring`: nowe zdjęcie wjeżdża w kierunku ruchu na miękkiej sprężynie, a duch poprzedniego
+ * (osobny `<img class="kpt-galleria__ghost">` pod nim) cofa się wolniej i przygasa - paralaksa.
+ * `fade` i systemowe "ogranicz ruch": krótkie przenikanie; `none`: nic.
+ *
+ * Nowe zdjęcie, które jeszcze się nie zdekodowało, czeka niewidoczne - do tego czasu widać ducha,
+ * a nie pustą scenę.
+ */
+export declare function playGallerySlide(options: KptGallerySlideOptions): void;
+/** Zatrzymuje przesuw i zdejmuje ducha - przy zniszczeniu galerii albo wymianie listy. */
+export declare function stopGallerySlide(stage: HTMLElement, image?: HTMLImageElement | null): void;
+/**
+ * Przewija pasek tak, żeby miniatura była cała widoczna - i tylko wtedy, gdy nie jest.
+ * Przewijany jest sam pasek (`scrollBy`), nigdy strona.
+ */
+export declare function revealThumb(strip: HTMLElement, thumb: HTMLElement, smooth?: boolean): void;
+/** Przewija pasek o 80% szerokości; `direction` logiczny: -1 w stronę początku, 1 w stronę końca. */
+export declare function scrollStrip(strip: HTMLElement, direction: 1 | -1): void;
+/**
+ * Śledzi, czy pasek da się przewinąć, i wystawia to na `target` jako atrybuty `data-scroll-start`
+ * i `data-scroll-end` (logiczne - w RTL "początek" jest po prawej). Styl wygasza po nich krawędzie
+ * i pokazuje strzałki paska. `update()` - po zmianie listy miniatur; `dispose()` - przy zniszczeniu.
+ */
+export declare function trackStripEdges(strip: HTMLElement, target: HTMLElement): {
+    update: () => void;
+    dispose: () => void;
+};
+/**
+ * Przeciąganie paska myszą i piórem (dotyk przewija się natywnie). Ruch o mniej niż 5 px to
+ * zwykły klik w miniaturę; dłuższy to przeciągnięcie - wtedy klik po puszczeniu jest połykany,
+ * a pasek jedzie dalej z bezwładnością (przy "ogranicz ruch" staje od razu). Klasa
+ * `is-dragging` na pasku na czas przeciągania. Zwraca funkcję odpinającą.
+ */
+export declare function attachDragScroll(strip: HTMLElement): () => void;

package/dist/gallery-dom.js

@@ -0,0 +1,238 @@
+import { layoutMotionAllowed } from "./dom.js";
+import { springEasing } from "./spring.js";
+import { KPT_GALLERY_FADE_MS, KPT_GALLERY_SLIDE_MS, KPT_INERTIA_STOP, gallerySlide, inertiaStep, revealDelta, stripEdges, } from "./gallery.js";
+const ANIMATION_ID = 'kpt-gallery-motion';
+const EASE_OUT = 'cubic-bezier(0.2, 0, 0, 1)';
+/** Margines odsłaniania miniatury - szerszy niż wygaszone krawędzie paska, żeby nie stała pod nimi. */
+const REVEAL_PAD = 40;
+/** Duch poprzedniego zdjęcia w scenie - jeden na scenę, nowy przesuw zdejmuje stary od razu. */
+const ghosts = new WeakMap();
+function clearGhost(stage) {
+    ghosts.get(stage)?.remove();
+    ghosts.delete(stage);
+}
+/**
+ * Zmiana zdjęcia w galerii. Wołać po renderze, gdy zdjęcie główne ma już nowy `src`.
+ * `spring`: nowe zdjęcie wjeżdża w kierunku ruchu na miękkiej sprężynie, a duch poprzedniego
+ * (osobny `<img class="kpt-galleria__ghost">` pod nim) cofa się wolniej i przygasa - paralaksa.
+ * `fade` i systemowe "ogranicz ruch": krótkie przenikanie; `none`: nic.
+ *
+ * Nowe zdjęcie, które jeszcze się nie zdekodowało, czeka niewidoczne - do tego czasu widać ducha,
+ * a nie pustą scenę.
+ */
+export function playGallerySlide(options) {
+    const { stage, image, previousSrc, direction, motion } = options;
+    clearGhost(stage);
+    // Bez WAAPI (np. jsdom w testach aplikacji) zdjęcie zmienia się bez ruchu.
+    if (!animatable(image))
+        return;
+    cancelOn(image);
+    image.style.removeProperty('opacity');
+    if (motion === 'none' || !previousSrc)
+        return;
+    const ghost = document.createElement('img');
+    ghost.className = 'kpt-galleria__ghost';
+    ghost.src = previousSrc;
+    ghost.alt = '';
+    ghost.setAttribute('aria-hidden', 'true');
+    stage.insertBefore(ghost, image);
+    ghosts.set(stage, ghost);
+    const play = () => {
+        image.style.removeProperty('opacity');
+        if (ghosts.get(stage) !== ghost)
+            return;
+        let ms = KPT_GALLERY_FADE_MS;
+        if (motion === 'fade' || !layoutMotionAllowed()) {
+            image.animate({ opacity: [0, 1] }, { id: ANIMATION_ID, duration: ms, easing: EASE_OUT, fill: 'backwards' });
+        }
+        else {
+            ms = KPT_GALLERY_SLIDE_MS;
+            const slide = gallerySlide(direction, getComputedStyle(stage).direction === 'rtl');
+            image.animate({ transform: [...slide.incoming] }, { id: ANIMATION_ID, duration: ms, easing: springEasing(0.18), fill: 'backwards' });
+            image.animate({ filter: ['brightness(0.85)', 'brightness(1)'] }, { id: ANIMATION_ID, duration: ms, easing: EASE_OUT, fill: 'backwards' });
+            ghost.animate({ transform: [...slide.outgoing], filter: ['brightness(1)', 'brightness(0.45)'] }, { id: ANIMATION_ID, duration: ms, easing: EASE_OUT, fill: 'forwards' });
+        }
+        // Zegar, nie `finished`: anulowana animacja nigdy by go nie rozwiązała.
+        setTimeout(() => {
+            if (ghosts.get(stage) === ghost)
+                clearGhost(stage);
+        }, ms);
+    };
+    if (image.complete && image.naturalWidth > 0) {
+        play();
+    }
+    else {
+        image.style.opacity = '0';
+        // Błąd dekodowania nie przerywa - zdjęcie po prostu się pokaże.
+        void image.decode().catch(() => undefined).then(play);
+    }
+}
+/** Zatrzymuje przesuw i zdejmuje ducha - przy zniszczeniu galerii albo wymianie listy. */
+export function stopGallerySlide(stage, image) {
+    clearGhost(stage);
+    if (image && animatable(image))
+        cancelOn(image);
+    image?.style.removeProperty('opacity');
+}
+function animatable(el) {
+    return typeof el.animate === 'function' && typeof el.getAnimations === 'function';
+}
+function cancelOn(el) {
+    el.getAnimations().forEach((a) => {
+        if (a.id === ANIMATION_ID)
+            a.cancel();
+    });
+}
+/**
+ * Przewija pasek tak, żeby miniatura była cała widoczna - i tylko wtedy, gdy nie jest.
+ * Przewijany jest sam pasek (`scrollBy`), nigdy strona.
+ */
+export function revealThumb(strip, thumb, smooth = true) {
+    const s = strip.getBoundingClientRect();
+    const r = thumb.getBoundingClientRect();
+    const pad = Math.min(REVEAL_PAD, Math.max(0, (s.width - r.width) / 2));
+    const delta = revealDelta(r.left, r.right, s.left, s.right, pad);
+    if (Math.abs(delta) < 1 || typeof strip.scrollBy !== 'function')
+        return;
+    strip.scrollBy({ left: delta, behavior: smooth && layoutMotionAllowed() ? 'smooth' : 'auto' });
+}
+/** Przewija pasek o 80% szerokości; `direction` logiczny: -1 w stronę początku, 1 w stronę końca. */
+export function scrollStrip(strip, direction) {
+    if (typeof strip.scrollBy !== 'function')
+        return;
+    const physical = getComputedStyle(strip).direction === 'rtl' ? -direction : direction;
+    strip.scrollBy({ left: physical * strip.clientWidth * 0.8, behavior: layoutMotionAllowed() ? 'smooth' : 'auto' });
+}
+/**
+ * Śledzi, czy pasek da się przewinąć, i wystawia to na `target` jako atrybuty `data-scroll-start`
+ * i `data-scroll-end` (logiczne - w RTL "początek" jest po prawej). Styl wygasza po nich krawędzie
+ * i pokazuje strzałki paska. `update()` - po zmianie listy miniatur; `dispose()` - przy zniszczeniu.
+ */
+export function trackStripEdges(strip, target) {
+    const update = () => {
+        const edges = stripEdges(strip.scrollLeft, strip.clientWidth, strip.scrollWidth);
+        target.toggleAttribute('data-scroll-start', edges.start);
+        target.toggleAttribute('data-scroll-end', edges.end);
+    };
+    strip.addEventListener('scroll', update, { passive: true });
+    const ro = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update);
+    ro?.observe(strip);
+    update();
+    return {
+        update,
+        dispose: () => {
+            strip.removeEventListener('scroll', update);
+            ro?.disconnect();
+        },
+    };
+}
+/**
+ * Przeciąganie paska myszą i piórem (dotyk przewija się natywnie). Ruch o mniej niż 5 px to
+ * zwykły klik w miniaturę; dłuższy to przeciągnięcie - wtedy klik po puszczeniu jest połykany,
+ * a pasek jedzie dalej z bezwładnością (przy "ogranicz ruch" staje od razu). Klasa
+ * `is-dragging` na pasku na czas przeciągania. Zwraca funkcję odpinającą.
+ */
+export function attachDragScroll(strip) {
+    let pointer = -1;
+    let startX = 0;
+    let startScroll = 0;
+    let lastX = 0;
+    let lastT = 0;
+    let velocity = 0;
+    let dragging = false;
+    let swallowClick = false;
+    let raf = 0;
+    const stopGlide = () => {
+        if (raf)
+            cancelAnimationFrame(raf);
+        raf = 0;
+    };
+    const glide = (initial) => {
+        let v = initial;
+        let last = performance.now();
+        const frame = (now) => {
+            const step = inertiaStep(v, Math.min(32, now - last));
+            last = now;
+            v = step.velocity;
+            const before = strip.scrollLeft;
+            strip.scrollLeft += step.distance;
+            // Koniec bezwładności: prędkość zgasła albo pasek doszedł do krawędzi.
+            if (v === 0 || strip.scrollLeft === before) {
+                raf = 0;
+                return;
+            }
+            raf = requestAnimationFrame(frame);
+        };
+        raf = requestAnimationFrame(frame);
+    };
+    const onDown = (e) => {
+        if (e.pointerType === 'touch' || e.button !== 0)
+            return;
+        stopGlide();
+        pointer = e.pointerId;
+        startX = lastX = e.clientX;
+        lastT = e.timeStamp;
+        startScroll = strip.scrollLeft;
+        velocity = 0;
+        dragging = false;
+    };
+    const onMove = (e) => {
+        if (e.pointerId !== pointer)
+            return;
+        const dx = e.clientX - startX;
+        if (!dragging) {
+            if (Math.abs(dx) < 5)
+                return;
+            dragging = true;
+            strip.setPointerCapture(pointer);
+            strip.classList.add('is-dragging');
+        }
+        strip.scrollLeft = startScroll - dx;
+        const dt = e.timeStamp - lastT;
+        if (dt > 0)
+            velocity = 0.8 * ((lastX - e.clientX) / dt) + 0.2 * velocity;
+        lastX = e.clientX;
+        lastT = e.timeStamp;
+    };
+    const onUp = (e) => {
+        if (e.pointerId !== pointer)
+            return;
+        pointer = -1;
+        if (!dragging)
+            return;
+        dragging = false;
+        strip.classList.remove('is-dragging');
+        if (strip.hasPointerCapture(e.pointerId))
+            strip.releasePointerCapture(e.pointerId);
+        swallowClick = true;
+        setTimeout(() => (swallowClick = false), 0);
+        // Puszczenie po zatrzymaniu ręki nie rzuca paskiem.
+        if (layoutMotionAllowed() && Math.abs(velocity) > KPT_INERTIA_STOP && e.timeStamp - lastT < 80)
+            glide(velocity);
+    };
+    const onClick = (e) => {
+        if (!swallowClick)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        swallowClick = false;
+    };
+    const onDragStart = (e) => e.preventDefault();
+    strip.addEventListener('pointerdown', onDown);
+    strip.addEventListener('pointermove', onMove);
+    strip.addEventListener('pointerup', onUp);
+    strip.addEventListener('pointercancel', onUp);
+    strip.addEventListener('click', onClick, true);
+    strip.addEventListener('dragstart', onDragStart);
+    strip.addEventListener('wheel', stopGlide, { passive: true });
+    return () => {
+        stopGlide();
+        strip.removeEventListener('pointerdown', onDown);
+        strip.removeEventListener('pointermove', onMove);
+        strip.removeEventListener('pointerup', onUp);
+        strip.removeEventListener('pointercancel', onUp);
+        strip.removeEventListener('click', onClick, true);
+        strip.removeEventListener('dragstart', onDragStart);
+        strip.removeEventListener('wheel', stopGlide);
+    };
+}

package/dist/gallery.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Ruch galerii (`kpt-galleria`): przesuw zdjęć z paralaksą i pasek miniatur bez paska przewijania,
+ * prowadzony przeciąganiem. Tu sama arytmetyka - bez DOM, z testami; warstwa DOM to `gallery-dom.ts`.
+ */
+/** Czas przesuwu zdjęcia (miękka sprężyna) i krótkiego przenikania (`fade`, "ogranicz ruch"), ms. */
+export declare const KPT_GALLERY_SLIDE_MS = 620;
+export declare const KPT_GALLERY_FADE_MS = 200;
+/** O ile wolniej od nowego zdjęcia cofa się stare - paralaksa, w procentach szerokości sceny. */
+export declare const KPT_GALLERY_PARALLAX = 28;
+/** Klatki przesuwu: nowe zdjęcie wjeżdża, stare cofa się wolniej. */
+export interface KptGallerySlide {
+    readonly incoming: readonly [string, string];
+    readonly outgoing: readonly [string, string];
+}
+/**
+ * `direction` 1 = następne zdjęcie, -1 = poprzednie. Następne wjeżdża od strony końca wiersza:
+ * w LTR z prawej, w RTL z lewej - tak samo jak kolejność miniatur.
+ */
+export declare function gallerySlide(direction: 1 | -1, rtl?: boolean): KptGallerySlide;
+/**
+ * O ile przewinąć pasek, żeby miniatura była cała widoczna z marginesem `pad` - i ani piksela
+ * więcej: widoczna miniatura daje 0, więc pasek nie skacze przy każdym kliknięciu. Współrzędne
+ * fizyczne (prostokąty z ekranu), więc działa tak samo w RTL: dodatnia wartość przesuwa widok w prawo.
+ */
+export declare function revealDelta(itemLeft: number, itemRight: number, viewLeft: number, viewRight: number, pad?: number): number;
+/**
+ * Czy pasek da się przewinąć w stronę początku i końca. `scrollLeft` w RTL bywa ujemny (od 0 do
+ * `-max`), więc liczy się wartość bezwzględna - wynik jest logiczny, nie fizyczny.
+ */
+export declare function stripEdges(scrollLeft: number, clientWidth: number, scrollWidth: number): {
+    start: boolean;
+    end: boolean;
+};
+/** Prędkość (px/ms), poniżej której bezwładność się zatrzymuje. */
+export declare const KPT_INERTIA_STOP = 0.02;
+/**
+ * Jeden krok bezwładności po puszczeniu przeciągnięcia: prędkość gaśnie wykładniczo (`friction`
+ * na każde 16 ms), a droga to średnia prędkość w kroku razy czas. Niezależne od liczby klatek -
+ * na 120 Hz pasek zatrzymuje się w tym samym miejscu co na 60 Hz.
+ */
+export declare function inertiaStep(velocity: number, dt: number, friction?: number): {
+    velocity: number;
+    distance: number;
+};

package/dist/gallery.js

@@ -0,0 +1,56 @@
+/**
+ * Ruch galerii (`kpt-galleria`): przesuw zdjęć z paralaksą i pasek miniatur bez paska przewijania,
+ * prowadzony przeciąganiem. Tu sama arytmetyka - bez DOM, z testami; warstwa DOM to `gallery-dom.ts`.
+ */
+/** Czas przesuwu zdjęcia (miękka sprężyna) i krótkiego przenikania (`fade`, "ogranicz ruch"), ms. */
+export const KPT_GALLERY_SLIDE_MS = 620;
+export const KPT_GALLERY_FADE_MS = 200;
+/** O ile wolniej od nowego zdjęcia cofa się stare - paralaksa, w procentach szerokości sceny. */
+export const KPT_GALLERY_PARALLAX = 28;
+/**
+ * `direction` 1 = następne zdjęcie, -1 = poprzednie. Następne wjeżdża od strony końca wiersza:
+ * w LTR z prawej, w RTL z lewej - tak samo jak kolejność miniatur.
+ */
+export function gallerySlide(direction, rtl = false) {
+    const side = rtl ? -direction : direction;
+    return {
+        incoming: [`translateX(${side * 100}%)`, 'none'],
+        outgoing: ['none', `translateX(${side * -KPT_GALLERY_PARALLAX}%) scale(0.96)`],
+    };
+}
+/**
+ * O ile przewinąć pasek, żeby miniatura była cała widoczna z marginesem `pad` - i ani piksela
+ * więcej: widoczna miniatura daje 0, więc pasek nie skacze przy każdym kliknięciu. Współrzędne
+ * fizyczne (prostokąty z ekranu), więc działa tak samo w RTL: dodatnia wartość przesuwa widok w prawo.
+ */
+export function revealDelta(itemLeft, itemRight, viewLeft, viewRight, pad = 0) {
+    if (itemRight - itemLeft > viewRight - viewLeft - 2 * pad) {
+        // Miniatura szersza niż widok - wyrównaj do początku, reszty i tak nie zmieścimy.
+        return itemLeft - (viewLeft + pad);
+    }
+    if (itemLeft < viewLeft + pad)
+        return itemLeft - (viewLeft + pad);
+    if (itemRight > viewRight - pad)
+        return itemRight - (viewRight - pad);
+    return 0;
+}
+/**
+ * Czy pasek da się przewinąć w stronę początku i końca. `scrollLeft` w RTL bywa ujemny (od 0 do
+ * `-max`), więc liczy się wartość bezwzględna - wynik jest logiczny, nie fizyczny.
+ */
+export function stripEdges(scrollLeft, clientWidth, scrollWidth) {
+    const max = scrollWidth - clientWidth;
+    const at = Math.abs(scrollLeft);
+    return { start: max > 1 && at > 1, end: max > 1 && at < max - 1 };
+}
+/** Prędkość (px/ms), poniżej której bezwładność się zatrzymuje. */
+export const KPT_INERTIA_STOP = 0.02;
+/**
+ * Jeden krok bezwładności po puszczeniu przeciągnięcia: prędkość gaśnie wykładniczo (`friction`
+ * na każde 16 ms), a droga to średnia prędkość w kroku razy czas. Niezależne od liczby klatek -
+ * na 120 Hz pasek zatrzymuje się w tym samym miejscu co na 60 Hz.
+ */
+export function inertiaStep(velocity, dt, friction = 0.95) {
+    const next = velocity * Math.pow(friction, dt / 16);
+    return { velocity: Math.abs(next) < KPT_INERTIA_STOP ? 0 : next, distance: ((velocity + next) / 2) * dt };
+}

package/dist/index.d.ts

@@ -1,4 +1,12 @@
 export { springProgress, springEasing } from './spring.ts';
+export { zoomFlight, KPT_ZOOM_OPEN_MS, KPT_ZOOM_CLOSE_MS, KPT_ZOOM_FADE_MS } from './zoom.ts';
+export type { KptZoomFlight } from './zoom.ts';
+export { playZoomOpen, playZoomClose, stopZoomMotion } from './zoom-dom.ts';
+export type { KptZoomElements } from './zoom-dom.ts';
+export { gallerySlide, revealDelta, stripEdges, inertiaStep, KPT_GALLERY_SLIDE_MS, KPT_GALLERY_FADE_MS, KPT_GALLERY_PARALLAX, KPT_INERTIA_STOP, } from './gallery.ts';
+export type { KptGallerySlide } from './gallery.ts';
+export { playGallerySlide, stopGallerySlide, revealThumb, scrollStrip, trackStripEdges, attachDragScroll, } from './gallery-dom.ts';
+export type { KptGallerySlideOptions } from './gallery-dom.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';

package/dist/index.js

@@ -1,4 +1,8 @@
 export { springProgress, springEasing } from "./spring.js";
+export { zoomFlight, KPT_ZOOM_OPEN_MS, KPT_ZOOM_CLOSE_MS, KPT_ZOOM_FADE_MS } from "./zoom.js";
+export { playZoomOpen, playZoomClose, stopZoomMotion } from "./zoom-dom.js";
+export { gallerySlide, revealDelta, stripEdges, inertiaStep, KPT_GALLERY_SLIDE_MS, KPT_GALLERY_FADE_MS, KPT_GALLERY_PARALLAX, KPT_INERTIA_STOP, } from "./gallery.js";
+export { playGallerySlide, stopGallerySlide, revealThumb, scrollStrip, trackStripEdges, attachDragScroll, } from "./gallery-dom.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";

package/dist/zoom-dom.d.ts

@@ -0,0 +1,30 @@
+import type { KptEnterMotion } from './config.ts';
+/** Elementy podglądu zdjęcia - te same w obu portach `kpt-image`. */
+export interface KptZoomElements {
+    /** Miniatura, z której podgląd wylatuje i do której wraca. */
+    readonly thumb: HTMLElement;
+    /** Duże zdjęcie w podglądzie. */
+    readonly image: HTMLImageElement;
+    /** Natywne okno - jego `::backdrop` przenika się razem z lotem. */
+    readonly dialog: HTMLDialogElement;
+    /** Przycisk zamknięcia - pojawia się po starcie lotu, znika pierwszy. */
+    readonly close?: HTMLElement | null;
+}
+/**
+ * Otwarcie podglądu. Wołać zaraz po `showModal()` - przed malowaniem, żeby pierwsza klatka
+ * już stała na miniaturze. `spring` (domyślny): zdjęcie wylatuje z miniatury i ląduje na miękkiej
+ * sprężynie, a miniatura na ten czas znika - zdjęcie opuściło swoje miejsce; `fade` i systemowe
+ * "ogranicz ruch": samo przenikanie; `none`: nic.
+ *
+ * Zdjęcie bez wymiarów (plik jeszcze się dekoduje) nie ma celu lotu - czekamy na `decode()`,
+ * a do tego czasu jest niewidoczne, żeby nie mignęło na środku przed startem.
+ */
+export declare function playZoomOpen(els: KptZoomElements, motion: KptEnterMotion): void;
+/**
+ * Zamknięcie podglądu: zdjęcie wraca do miniatury sprężyną z krótkim domknięciem, tło gaśnie.
+ * Zwraca czas ruchu w ms - dopiero po nim wołający zamyka okno (`dialog.close()`), a potem
+ * `stopZoomMotion`. `0` = zamknij od razu.
+ */
+export declare function playZoomClose(els: KptZoomElements, motion: KptEnterMotion): number;
+/** Sprząta po podglądzie: zatrzymuje ruch, zdejmuje style i oddaje miniaturę na jej miejsce. */
+export declare function stopZoomMotion(els: KptZoomElements): void;

package/dist/zoom-dom.js

@@ -0,0 +1,141 @@
+import { layoutMotionAllowed } from "./dom.js";
+import { springEasing } from "./spring.js";
+import { KPT_ZOOM_CLOSE_MS, KPT_ZOOM_FADE_MS, KPT_ZOOM_OPEN_MS, zoomFlight } from "./zoom.js";
+const ANIMATION_ID = 'kpt-zoom-motion';
+const EASE_OUT = 'cubic-bezier(0.2, 0, 0, 1)';
+const EASE_IN = 'cubic-bezier(0.4, 0, 1, 1)';
+function rectOf(el) {
+    const r = el.getBoundingClientRect();
+    return { x: r.left, y: r.top, width: r.width, height: r.height };
+}
+function radiusOf(el) {
+    return parseFloat(getComputedStyle(el).borderTopLeftRadius) || 0;
+}
+/** `::backdrop` animowany przez WAAPI; przeglądarka bez `pseudoElement` po prostu go nie animuje. */
+function animateBackdrop(dialog, opacity, duration, easing) {
+    try {
+        dialog.animate({ opacity }, { id: ANIMATION_ID, pseudoElement: '::backdrop', duration, easing, fill: 'forwards' });
+    }
+    catch {
+        /* bez wsparcia pseudoElement - tło pojawia się od razu */
+    }
+}
+function fadeOpen(els) {
+    els.dialog.animate({ opacity: [0, 1] }, { id: ANIMATION_ID, duration: KPT_ZOOM_FADE_MS, easing: EASE_OUT, fill: 'backwards' });
+    animateBackdrop(els.dialog, [0, 1], KPT_ZOOM_FADE_MS, EASE_OUT);
+}
+/** Bez WAAPI (np. jsdom w testach aplikacji) ruchu nie ma - podgląd po prostu się otwiera i zamyka. */
+function animatable() {
+    return typeof Element !== 'undefined' && typeof Element.prototype.animate === 'function';
+}
+/**
+ * Pokolenie podglądu dla zdjęcia. Otwarcie czekające na `decode()` sprawdza je przed startem:
+ * zamknięcie albo kolejne otwarcie w międzyczasie je podbija, więc spóźniony lot się nie odpala.
+ */
+const generation = new WeakMap();
+function nextGeneration(image) {
+    const value = (generation.get(image) ?? 0) + 1;
+    generation.set(image, value);
+    return value;
+}
+/**
+ * Otwarcie podglądu. Wołać zaraz po `showModal()` - przed malowaniem, żeby pierwsza klatka
+ * już stała na miniaturze. `spring` (domyślny): zdjęcie wylatuje z miniatury i ląduje na miękkiej
+ * sprężynie, a miniatura na ten czas znika - zdjęcie opuściło swoje miejsce; `fade` i systemowe
+ * "ogranicz ruch": samo przenikanie; `none`: nic.
+ *
+ * Zdjęcie bez wymiarów (plik jeszcze się dekoduje) nie ma celu lotu - czekamy na `decode()`,
+ * a do tego czasu jest niewidoczne, żeby nie mignęło na środku przed startem.
+ */
+export function playZoomOpen(els, motion) {
+    stopZoomMotion(els);
+    if (motion === 'none' || !animatable())
+        return;
+    if (motion === 'fade' || !layoutMotionAllowed()) {
+        fadeOpen(els);
+        return;
+    }
+    const mine = nextGeneration(els.image);
+    const fly = () => {
+        if (generation.get(els.image) !== mine)
+            return;
+        els.image.style.removeProperty('opacity');
+        els.close?.style.removeProperty('opacity');
+        cancelBackdrop(els.dialog);
+        if (!els.dialog.open)
+            return;
+        const to = rectOf(els.image);
+        if (to.width === 0) {
+            fadeOpen(els);
+            return;
+        }
+        const radius = radiusOf(els.image);
+        const flight = zoomFlight(rectOf(els.thumb), to, radiusOf(els.thumb) || radius);
+        els.thumb.style.visibility = 'hidden';
+        els.image.animate({ transform: [flight.transform, 'none'], borderRadius: [`${flight.radiusFrom}px`, `${radius}px`] }, { id: ANIMATION_ID, duration: KPT_ZOOM_OPEN_MS, easing: springEasing(0.22), fill: 'backwards' });
+        animateBackdrop(els.dialog, [0, 1], 260, EASE_OUT);
+        els.close?.animate({ opacity: [0, 1], transform: ['scale(0.6)', 'none'] }, { id: ANIMATION_ID, duration: 320, delay: 220, easing: springEasing(0.32), fill: 'backwards' });
+    };
+    if (els.image.complete && els.image.naturalWidth > 0) {
+        fly();
+    }
+    else {
+        // Do startu lotu nic nie może się pokazać: ani zdjęcie na środku, ani tło i przycisk x
+        // w pełnym kryciu (potem zgasłyby i wróciły z animacją).
+        els.image.style.opacity = '0';
+        if (els.close)
+            els.close.style.opacity = '0';
+        animateBackdrop(els.dialog, [0, 0], 60_000, 'linear');
+        // Błąd dekodowania nie przerywa - `fly` bez wymiarów zdjęcia schodzi do przenikania.
+        void els.image.decode().catch(() => undefined).then(fly);
+    }
+}
+/** Zdejmuje animacje `::backdrop` okna - `getAnimations()` okna ich nie obejmuje, więc z dokumentu. */
+function cancelBackdrop(dialog) {
+    document.getAnimations().forEach((a) => {
+        if (a.id === ANIMATION_ID && a.effect?.target === dialog)
+            a.cancel();
+    });
+}
+/**
+ * Zamknięcie podglądu: zdjęcie wraca do miniatury sprężyną z krótkim domknięciem, tło gaśnie.
+ * Zwraca czas ruchu w ms - dopiero po nim wołający zamyka okno (`dialog.close()`), a potem
+ * `stopZoomMotion`. `0` = zamknij od razu.
+ */
+export function playZoomClose(els, motion) {
+    nextGeneration(els.image);
+    if (motion === 'none' || !els.dialog.open || !animatable())
+        return 0;
+    if (motion === 'fade' || !layoutMotionAllowed()) {
+        els.dialog.animate({ opacity: [1, 0] }, { id: ANIMATION_ID, duration: KPT_ZOOM_FADE_MS, easing: EASE_IN, fill: 'forwards' });
+        animateBackdrop(els.dialog, [1, 0], KPT_ZOOM_FADE_MS, EASE_IN);
+        return KPT_ZOOM_FADE_MS;
+    }
+    // Zamknięcie w trakcie lotu: prostokąt celu mierzymy bez transformu otwarcia.
+    cancelOn(els.image);
+    els.image.style.removeProperty('opacity');
+    const radius = radiusOf(els.image);
+    const flight = zoomFlight(rectOf(els.thumb), rectOf(els.image), radiusOf(els.thumb) || radius);
+    els.image.animate({ transform: ['none', flight.transform], borderRadius: [`${radius}px`, `${flight.radiusFrom}px`] }, { id: ANIMATION_ID, duration: KPT_ZOOM_CLOSE_MS, easing: springEasing(0.32), fill: 'forwards' });
+    animateBackdrop(els.dialog, [1, 0], 220, EASE_IN);
+    els.close?.animate({ opacity: [1, 0] }, { id: ANIMATION_ID, duration: 120, fill: 'forwards' });
+    return KPT_ZOOM_CLOSE_MS;
+}
+function cancelOn(el) {
+    el?.getAnimations().forEach((a) => {
+        if (a.id === ANIMATION_ID)
+            a.cancel();
+    });
+}
+/** Sprząta po podglądzie: zatrzymuje ruch, zdejmuje style i oddaje miniaturę na jej miejsce. */
+export function stopZoomMotion(els) {
+    nextGeneration(els.image);
+    els.image.style.removeProperty('opacity');
+    els.close?.style.removeProperty('opacity');
+    els.thumb.style.removeProperty('visibility');
+    if (typeof Element === 'undefined' || typeof Element.prototype.getAnimations !== 'function')
+        return;
+    cancelOn(els.image);
+    cancelOn(els.close);
+    cancelBackdrop(els.dialog);
+}

package/dist/zoom.d.ts

@@ -0,0 +1,27 @@
+import type { KptRect } from './layout.ts';
+/**
+ * Lot podglądu zdjęcia (`kpt-image`): duże zdjęcie startuje dokładnie z miejsca miniatury
+ * i ląduje w swoim docelowym prostokącie - technika FLIP. Miniatura i podgląd pokazują ten sam
+ * plik, więc mają te same proporcje i wystarcza jedna skala.
+ */
+export interface KptZoomFlight {
+    /** `transform`, który kładzie podgląd (prostokąt `to`) na miniaturze (prostokąt `from`). */
+    readonly transform: string;
+    /** Skala tego położenia - do przeliczenia promienia rogów. */
+    readonly scale: number;
+    /**
+     * Promień rogów podglądu na starcie, w px. Skala zmniejsza też rogi, więc żeby w locie miały
+     * promień miniatury, podgląd startuje z promieniem podzielonym przez skalę.
+     */
+    readonly radiusFrom: number;
+}
+/** Czas otwarcia (miękka sprężyna) i zamknięcia (sprężyna z krótkim domknięciem), ms. */
+export declare const KPT_ZOOM_OPEN_MS = 640;
+export declare const KPT_ZOOM_CLOSE_MS = 460;
+/** Czas przenikania - wariant `fade` i "ogranicz ruch". */
+export declare const KPT_ZOOM_FADE_MS = 180;
+/**
+ * Położenie startowe lotu. Przy zerowej szerokości celu (zdjęcie jeszcze bez wymiarów) skala
+ * zostaje 1 - lepiej przesunięcie bez skali niż dzielenie przez zero.
+ */
+export declare function zoomFlight(from: KptRect, to: KptRect, thumbRadius: number): KptZoomFlight;

package/dist/zoom.js

@@ -0,0 +1,20 @@
+import { round } from "./spring.js";
+/** Czas otwarcia (miękka sprężyna) i zamknięcia (sprężyna z krótkim domknięciem), ms. */
+export const KPT_ZOOM_OPEN_MS = 640;
+export const KPT_ZOOM_CLOSE_MS = 460;
+/** Czas przenikania - wariant `fade` i "ogranicz ruch". */
+export const KPT_ZOOM_FADE_MS = 180;
+/**
+ * Położenie startowe lotu. Przy zerowej szerokości celu (zdjęcie jeszcze bez wymiarów) skala
+ * zostaje 1 - lepiej przesunięcie bez skali niż dzielenie przez zero.
+ */
+export function zoomFlight(from, to, thumbRadius) {
+    const scale = to.width > 0 ? from.width / to.width : 1;
+    const dx = from.x + from.width / 2 - (to.x + to.width / 2);
+    const dy = from.y + from.height / 2 - (to.y + to.height / 2);
+    return {
+        transform: `translate(${round(dx, 1)}px, ${round(dy, 1)}px) scale(${round(scale, 4)})`,
+        scale,
+        radiusFrom: scale > 0 ? round(thumbRadius / scale, 2) : thumbRadius,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@konce-pt/motion",
-  "version": "0.16.1",
-  "description": "Motion core for Koncept UI - spring curves sampled to linear() and FLIP flight plans for layout changes. Framework-free TypeScript, zero runtime dependencies.",
+  "version": "0.18.0",
+  "description": "Motion core for Koncept UI - spring curves sampled to linear(), FLIP flight plans for layout changes, loader, image zoom and gallery motion. Framework-free TypeScript, zero runtime dependencies.",
   "license": "MIT",
   "author": "konce.pt",
   "homepage": "https://ui.konce.pt/",