@vkontakte/vkui 7.0.1 → 7.1.0

package/src/components/CarouselBase/CarouselBase.tsx

@@ -0,0 +1,502 @@
+'use client';
+
+import * as React from 'react';
+import { classNames } from '@vkontakte/vkjs';
+import { useAdaptivityHasPointer } from '../../hooks/useAdaptivityHasPointer';
+import { useExternRef } from '../../hooks/useExternRef';
+import { useMutationObserver } from '../../hooks/useMutationObserver';
+import { useResizeObserver } from '../../hooks/useResizeObserver';
+import { useDOM } from '../../lib/dom';
+import { useIsomorphicLayoutEffect } from '../../lib/useIsomorphicLayoutEffect';
+import { warnOnce } from '../../lib/warnOnce';
+import { RootComponent } from '../RootComponent/RootComponent';
+import { type CustomTouchEvent } from '../Touch/Touch';
+import { Bullets } from './Bullets';
+import { CarouselViewPort } from './CarouselViewPort';
+import { ScrollArrows } from './ScrollArrows';
+import {
+  ANIMATION_DURATION,
+  CONTROL_ELEMENTS_STATE,
+  SLIDE_THRESHOLD,
+  SLIDES_MANAGER_STATE,
+} from './constants';
+import { calcMax, calcMin, calculateIndent, getLoopPoints, getTargetIndex } from './helpers';
+import { useSlideAnimation } from './hooks';
+import {
+  type BaseGalleryProps,
+  type ControlElementsState,
+  type GallerySlidesState,
+  type SlidesManagerState,
+} from './types';
+import styles from './CarouselBase.module.css';
+
+const warn = warnOnce('Gallery');
+
+export const CarouselBase = ({
+  bullets = false,
+  getRootRef,
+  children,
+  slideWidth = '100%',
+  slideIndex = 0,
+  dragDisabled = false,
+  resizeSource = 'window',
+  onDragStart,
+  onDragEnd,
+  onChange,
+  onPrevClick,
+  onNextClick,
+  align = 'left',
+  showArrows,
+  getRef,
+  arrowSize,
+  arrowAreaHeight,
+  slideTestId,
+  bulletTestId,
+  nextArrowTestId,
+  prevArrowTestId,
+  looped = false,
+  ...restProps
+}: BaseGalleryProps): React.ReactNode => {
+  const slidesStore = React.useRef<Record<string, HTMLDivElement | null>>({});
+  const slidesManager = React.useRef<SlidesManagerState>(SLIDES_MANAGER_STATE);
+
+  const rootRef = useExternRef(getRootRef);
+  const viewportRef = useExternRef(getRef);
+  const layerRef = React.useRef<HTMLDivElement>(null);
+  const animationFrameRef = React.useRef<ReturnType<typeof requestAnimationFrame> | null>(null);
+  const shiftXCurrentRef = React.useRef<number>(0);
+  const shiftXDeltaRef = React.useRef<number>(0);
+  const initialized = React.useRef<boolean>(false);
+  const { addToAnimationQueue, getAnimateFunction, startAnimation } = useSlideAnimation();
+  const isDragging = React.useRef(false);
+
+  const [controlElementsState, setControlElementsState] =
+    React.useState<ControlElementsState>(CONTROL_ELEMENTS_STATE);
+
+  const hasPointer = useAdaptivityHasPointer();
+
+  const isCenterAlign = align === 'center';
+
+  /*
+   * Считает отступ слоя галереи во время драга
+   * Используется только для looped=false галереи
+   * так как только у нее есть пределы по краям
+   */
+  const calculateDragIndent = () => {
+    const localMax = slidesManager.current.max ?? 0;
+    const localMin = slidesManager.current.min ?? 0;
+    const indent = shiftXCurrentRef.current + shiftXDeltaRef.current;
+
+    if (indent > localMax) {
+      return localMax + Number((indent - localMax) / 3);
+    } else if (indent < localMin) {
+      return localMin + Number((indent - localMin) / 3);
+    }
+
+    return indent;
+  };
+
+  const calculateCanSlideLeft = () => {
+    if (looped) {
+      return !slidesManager.current.isFullyVisible;
+    }
+    return !slidesManager.current.isFullyVisible && shiftXCurrentRef.current < 0;
+  };
+
+  const calculateCanSlideRight = () => {
+    if (looped) {
+      return !slidesManager.current.isFullyVisible;
+    }
+    return (
+      !slidesManager.current.isFullyVisible &&
+      // we can't move right when gallery layer fully scrolled right, if gallery aligned by left side
+      ((align === 'left' &&
+        slidesManager.current.containerWidth - shiftXCurrentRef.current <
+          (slidesManager.current.layerWidth ?? 0)) ||
+        // otherwise we need to check current slide index (align = right or align = center)
+        (align !== 'left' && slideIndex < slidesManager.current.slides.length - 1))
+    );
+  };
+
+  const transformCssStyles = (shiftX: number, animation = false) => {
+    shiftX = Math.round(shiftX);
+    if (looped) {
+      slidesManager.current.loopPoints.forEach((loopPoint) => {
+        const { target, index } = loopPoint;
+        const slide = slidesStore.current[index];
+        if (slide) {
+          slide.style.transform = `translate3d(${target(shiftX)}px, 0, 0)`;
+        }
+      });
+    } else {
+      Object.values(slidesStore.current).forEach((slide) => {
+        if (slide) {
+          slide.style.transform = '';
+        }
+      });
+    }
+
+    if (layerRef.current) {
+      const indent = isDragging.current && !looped ? calculateDragIndent() : shiftX;
+
+      layerRef.current.style.transform = `translate3d(${indent}px, 0, 0)`;
+      layerRef.current.style.transition = animation
+        ? `transform ${ANIMATION_DURATION}ms cubic-bezier(.1, 0, .25, 1)`
+        : '';
+    }
+  };
+
+  const requestTransform = (shiftX: number, animation = false) => {
+    const { snaps, contentSize, slides } = slidesManager.current;
+
+    if (animationFrameRef.current !== null) {
+      cancelAnimationFrame(animationFrameRef.current);
+    }
+    animationFrameRef.current = requestAnimationFrame(() => {
+      if (looped && shiftX > snaps[0]) {
+        shiftXCurrentRef.current = -contentSize + snaps[0];
+        shiftX = shiftXCurrentRef.current + shiftXDeltaRef.current;
+      }
+      const lastPoint = slides[slides.length - 1].width + slides[slides.length - 1].coordX;
+
+      if (looped && shiftX <= -lastPoint) {
+        shiftXCurrentRef.current = Math.abs(shiftXDeltaRef.current) + snaps[0];
+      }
+      transformCssStyles(shiftX, animation);
+    });
+  };
+
+  const initializeSlides = () => {
+    if (!rootRef.current || !viewportRef.current) {
+      return;
+    }
+    let localSlides =
+      React.Children.map(children, (_item, i): GallerySlidesState => {
+        const elem = slidesStore.current[i] || { offsetLeft: 0, offsetWidth: 0 };
+        return { coordX: elem.offsetLeft, width: elem.offsetWidth };
+      }) || [];
+
+    if (localSlides.length === 0) {
+      initialized.current = false;
+      return;
+    }
+
+    const containerWidth = rootRef.current.offsetWidth;
+    const viewportOffsetWidth = viewportRef.current.offsetWidth;
+    const layerWidth = localSlides.reduce((val, slide) => slide.width + val, 0);
+
+    if (process.env.NODE_ENV === 'development' && looped) {
+      let remainingWidth = containerWidth;
+      let slideIndex = 0;
+
+      while (remainingWidth > 0 && slideIndex < localSlides.length) {
+        remainingWidth -= localSlides[slideIndex].width;
+        slideIndex++;
+      }
+      if (remainingWidth <= 0 && slideIndex === localSlides.length) {
+        warn(
+          'Ширины слайдов недостаточно для корректной работы свойства "looped". Пожалуйста, сделайте её больше.',
+        );
+      }
+    }
+
+    const currentSlideOffsetOnCenterAlignment =
+      (containerWidth - (localSlides[slideIndex]?.width ?? 0)) / 2;
+    const isFullyVisible =
+      align === 'center'
+        ? layerWidth + currentSlideOffsetOnCenterAlignment <= containerWidth
+        : layerWidth <= containerWidth;
+
+    slidesManager.current = {
+      ...slidesManager.current,
+      layerWidth,
+      containerWidth,
+      viewportOffsetWidth,
+      slides: localSlides,
+      isFullyVisible,
+      max: looped
+        ? null
+        : calcMax({
+            slides: localSlides,
+            containerWidth,
+            isCenterAlign,
+          }),
+      min: looped
+        ? null
+        : calcMin({
+            containerWidth,
+            layerWidth,
+            slides: localSlides,
+            viewportOffsetWidth,
+            align,
+          }),
+    };
+    const snaps = localSlides.map((_, index) =>
+      calculateIndent(index, slidesManager.current, isCenterAlign, looped),
+    );
+
+    let contentSize = -snaps[snaps.length - 1] + localSlides[localSlides.length - 1].width;
+    if (align === 'center') {
+      contentSize += snaps[0];
+    }
+
+    slidesManager.current.snaps = snaps;
+    slidesManager.current.contentSize = contentSize;
+    if (looped) {
+      slidesManager.current.loopPoints = getLoopPoints(slidesManager.current, containerWidth);
+    }
+
+    shiftXCurrentRef.current = snaps[slideIndex];
+    initialized.current = true;
+
+    setControlElementsState({
+      canSlideLeft: calculateCanSlideLeft(),
+      canSlideRight: calculateCanSlideRight(),
+      isDraggable: !(dragDisabled || slidesManager.current.isFullyVisible),
+    });
+    requestTransform(shiftXCurrentRef.current);
+  };
+
+  const onResize = () => {
+    if (initialized.current) {
+      initializeSlides();
+    }
+  };
+  const { window } = useDOM();
+  useResizeObserver(resizeSource === 'element' ? rootRef : window, onResize);
+
+  const loopedSlideChangePerform = () => {
+    const { snaps, slides } = slidesManager.current;
+    const indent = snaps[slideIndex];
+    let startPoint = shiftXCurrentRef.current;
+
+    /**
+     * Переключаемся с последнего элемента на первый
+     * Для корректной анимации мы прокручиваем последний слайд на всю длину (shiftX) "вперед"
+     * В конце анимации при отрисовке следующего кадра задаем всем слайдам начальные значения
+     */
+    if (indent === snaps[0] && shiftXCurrentRef.current <= snaps[snaps.length - 1]) {
+      const distance =
+        Math.abs(snaps[snaps.length - 1]) + slides[slides.length - 1].width + startPoint;
+
+      addToAnimationQueue(
+        getAnimateFunction((progress) => {
+          const shiftX = startPoint + progress * distance * -1;
+
+          transformCssStyles(shiftX);
+
+          if (shiftX <= snaps[snaps.length - 1] - slides[slides.length - 1].width) {
+            requestAnimationFrame(() => {
+              shiftXCurrentRef.current = indent;
+              transformCssStyles(snaps[0]);
+            });
+          }
+        }),
+      );
+      /**
+       * Переключаемся с первого слайда на последний
+       * Для корректной анимации сначала задаем первым видимым слайдам смещение
+       * В следующем кадре начинаем анимация прокрутки "назад"
+       */
+    } else if (indent === snaps[snaps.length - 1] && shiftXCurrentRef.current === snaps[0]) {
+      startPoint = indent - slides[slides.length - 1].width;
+
+      addToAnimationQueue(() => {
+        requestAnimationFrame(() => {
+          const shiftX = indent - slides[slides.length - 1].width;
+          transformCssStyles(shiftX);
+
+          getAnimateFunction((progress) => {
+            transformCssStyles(startPoint + progress * slides[slides.length - 1].width);
+          })();
+        });
+      });
+      /**
+       * Если не обработаны `corner`-кейсы выше, то просто проигрываем анимацию смещения
+       */
+    } else {
+      addToAnimationQueue(() => {
+        const distance = Math.abs(indent - startPoint);
+        let direction = startPoint <= indent ? 1 : -1;
+
+        getAnimateFunction((progress) => {
+          const shiftX = startPoint + progress * distance * direction;
+          transformCssStyles(shiftX);
+        })();
+      });
+    }
+  };
+
+  const simpleSlideChangePerform = () => {
+    const { snaps } = slidesManager.current;
+    const startPoint = shiftXCurrentRef.current;
+    const endPoint = snaps[slideIndex];
+    const distance = endPoint - startPoint;
+    addToAnimationQueue(
+      getAnimateFunction((progress) => transformCssStyles(startPoint + distance * progress)),
+    );
+  };
+
+  useIsomorphicLayoutEffect(
+    function performSlideChange() {
+      if (!initialized.current) {
+        return;
+      }
+      const { snaps } = slidesManager.current;
+      const indent = snaps[slideIndex];
+
+      if (looped) {
+        loopedSlideChangePerform();
+      } else {
+        simpleSlideChangePerform();
+      }
+
+      startAnimation();
+
+      shiftXCurrentRef.current = indent;
+
+      setControlElementsState((v) => ({
+        ...v,
+        canSlideLeft: calculateCanSlideLeft(),
+        canSlideRight: calculateCanSlideRight(),
+      }));
+    },
+    [slideIndex],
+  );
+
+  useIsomorphicLayoutEffect(
+    function updateIsDraggable() {
+      setControlElementsState((v) => ({
+        ...v,
+        isDraggable: !(dragDisabled || slidesManager.current.isFullyVisible),
+      }));
+    },
+    [dragDisabled],
+  );
+
+  useMutationObserver(layerRef, initializeSlides);
+
+  useIsomorphicLayoutEffect(initializeSlides, [align, slideWidth, looped]);
+
+  const calculateMinDeltaXToSlide = () => {
+    return slidesManager.current.slides[slideIndex].width * SLIDE_THRESHOLD;
+  };
+
+  const slideLeft = (event: React.MouseEvent) => {
+    if (slideIndex > 0) {
+      shiftXCurrentRef.current += calculateMinDeltaXToSlide();
+    }
+    onChange?.(
+      (slideIndex - 1 + slidesManager.current.slides.length) % slidesManager.current.slides.length,
+    );
+    onPrevClick?.(event);
+  };
+
+  const slideRight = (event: React.MouseEvent) => {
+    if (slideIndex < slidesManager.current.slides.length - 1) {
+      shiftXCurrentRef.current -= calculateMinDeltaXToSlide();
+    }
+    onChange?.((slideIndex + 1) % slidesManager.current.slides.length);
+    onNextClick?.(event);
+  };
+
+  const onStart = (e: CustomTouchEvent) => {
+    e.originalEvent.stopPropagation();
+    if (controlElementsState.isDraggable) {
+      onDragStart?.(e);
+      shiftXCurrentRef.current = slidesManager.current.snaps[slideIndex];
+      shiftXDeltaRef.current = 0;
+    }
+  };
+
+  const onMoveX = (e: CustomTouchEvent) => {
+    if (controlElementsState.isDraggable) {
+      e.originalEvent.preventDefault();
+
+      if (e.isSlideX) {
+        isDragging.current = true;
+        if (shiftXDeltaRef.current !== e.shiftX) {
+          shiftXDeltaRef.current = e.shiftX;
+          requestTransform(shiftXCurrentRef.current + shiftXDeltaRef.current);
+        }
+      }
+    }
+  };
+
+  const onEnd = (e: CustomTouchEvent) => {
+    if (controlElementsState.isDraggable) {
+      isDragging.current = false;
+      let targetIndex = slideIndex;
+      if (e.isSlide) {
+        targetIndex = getTargetIndex(
+          slidesManager.current.slides,
+          slideIndex,
+          shiftXCurrentRef.current,
+          shiftXDeltaRef.current,
+          looped,
+        );
+      }
+      onDragEnd?.(e, targetIndex);
+
+      if (targetIndex !== slideIndex) {
+        shiftXCurrentRef.current = shiftXCurrentRef.current + shiftXDeltaRef.current;
+        onChange?.(targetIndex);
+      } else {
+        const initialShiftX = slidesManager.current.snaps[targetIndex];
+        requestTransform(initialShiftX, true);
+      }
+    }
+  };
+
+  const setSlideRef = (slideRef: HTMLDivElement | null, slideIndex: number) => {
+    slidesStore.current[slideIndex] = slideRef;
+  };
+
+  const { isDraggable, canSlideRight, canSlideLeft } = controlElementsState;
+
+  return (
+    <RootComponent
+      {...restProps}
+      baseClassName={classNames(
+        styles.host,
+        slideWidth === 'custom' && styles.customWidth,
+        isDraggable && styles.draggable,
+      )}
+      getRootRef={rootRef}
+    >
+      <CarouselViewPort
+        slideWidth={slideWidth}
+        slideTestId={slideTestId}
+        onStart={onStart}
+        onMoveX={onMoveX}
+        onEnd={onEnd}
+        getRootRef={viewportRef}
+        layerRef={layerRef}
+        setSlideRef={setSlideRef}
+      >
+        {children}
+      </CarouselViewPort>
+
+      {bullets && (
+        <Bullets
+          bullets={bullets}
+          slideIndex={slideIndex}
+          count={React.Children.count(children)}
+          bulletTestId={bulletTestId}
+        />
+      )}
+      <ScrollArrows
+        hasPointer={hasPointer}
+        canSlideLeft={canSlideLeft}
+        canSlideRight={canSlideRight}
+        onSlideRight={slideRight}
+        onSlideLeft={slideLeft}
+        showArrows={showArrows}
+        arrowSize={arrowSize}
+        arrowAreaHeight={arrowAreaHeight}
+        prevArrowTestId={prevArrowTestId}
+        nextArrowTestId={nextArrowTestId}
+      />
+    </RootComponent>
+  );
+};

package/src/components/CarouselBase/CarouselViewPort.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import * as React from 'react';
+import { type HasChildren, type HasRootRef } from '../../types';
+import { type CustomTouchEvent, Touch } from '../Touch/Touch';
+import { type BaseGalleryProps } from './types';
+import styles from './CarouselBase.module.css';
+
+type GalleryViewPortProps = Pick<BaseGalleryProps, 'slideWidth' | 'slideTestId'> &
+  HasRootRef<HTMLElement> &
+  HasChildren & {
+    onStart: (e: CustomTouchEvent) => void;
+    onMoveX: (e: CustomTouchEvent) => void;
+    onEnd: (e: CustomTouchEvent) => void;
+    setSlideRef: (slideRef: HTMLDivElement | null, slideIndex: number) => void;
+    layerRef?: React.Ref<HTMLDivElement>;
+  };
+
+export const CarouselViewPort: React.FC<GalleryViewPortProps> = ({
+  slideTestId,
+  slideWidth,
+  onStart,
+  onMoveX,
+  onEnd,
+  getRootRef,
+  layerRef,
+  children,
+  setSlideRef,
+}) => {
+  return (
+    <Touch
+      className={styles.viewport}
+      onStartX={onStart}
+      onMoveX={onMoveX}
+      onEnd={onEnd}
+      style={{ width: slideWidth === 'custom' ? '100%' : slideWidth }}
+      noSlideClick
+      getRootRef={getRootRef}
+    >
+      <div className={styles.layer} ref={layerRef}>
+        {React.Children.map(children, (item: React.ReactNode, i: number) => (
+          <div
+            className={styles.slide}
+            key={`slide-${i}`}
+            data-testid={slideTestId?.(i)}
+            ref={(el) => setSlideRef(el, i)}
+          >
+            {item}
+          </div>
+        ))}
+      </div>
+    </Touch>
+  );
+};

package/src/components/CarouselBase/ScrollArrows.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import * as React from 'react';
+import { classNames } from '@vkontakte/vkjs';
+import { ScrollArrow } from '../ScrollArrow/ScrollArrow';
+import { type BaseGalleryProps } from './types';
+import styles from './CarouselBase.module.css';
+
+const stylesArrowAreaHeight = {
+  stretch: styles.arrowAreaStretch,
+  fit: styles.arrowAreaFit,
+};
+
+export const getArrowClassName = (
+  side: 'start' | 'end',
+  arrowAreaHeight: Exclude<BaseGalleryProps['arrowAreaHeight'], undefined>,
+) => {
+  return classNames(
+    styles.arrow,
+    side === 'start' ? styles.arrowStart : styles.arrowEnd,
+    stylesArrowAreaHeight[arrowAreaHeight],
+  );
+};
+
+export interface ScrollArrowsTestIds {
+  /**
+   * Передает атрибут `data-testid` для кнопки перехода к следующему слайду
+   */
+  nextArrowTestId?: string;
+  /**
+   * Передает атрибут `data-testid` для кнопки перехода к предыдущему слайду
+   */
+  prevArrowTestId?: string;
+}
+
+interface ScrollArrowsProps
+  extends Pick<BaseGalleryProps, 'showArrows' | 'arrowSize' | 'arrowAreaHeight'>,
+    ScrollArrowsTestIds {
+  hasPointer?: boolean;
+  canSlideLeft: boolean;
+  canSlideRight: boolean;
+  onSlideLeft: (e: React.MouseEvent) => void;
+  onSlideRight: (e: React.MouseEvent) => void;
+}
+
+export const ScrollArrows: React.FC<ScrollArrowsProps> = ({
+  hasPointer,
+  canSlideLeft,
+  canSlideRight,
+  onSlideRight,
+  onSlideLeft,
+  showArrows = false,
+  arrowSize = 'm',
+  arrowAreaHeight = 'stretch',
+  nextArrowTestId,
+  prevArrowTestId,
+}) => {
+  return showArrows && hasPointer ? (
+    <>
+      {canSlideLeft && (
+        <ScrollArrow
+          className={getArrowClassName('start', arrowAreaHeight)}
+          direction="left"
+          onClick={onSlideLeft}
+          size={arrowSize}
+          data-testid={prevArrowTestId}
+        />
+      )}
+      {canSlideRight && (
+        <ScrollArrow
+          className={getArrowClassName('end', arrowAreaHeight)}
+          direction="right"
+          onClick={onSlideRight}
+          size={arrowSize}
+          data-testid={nextArrowTestId}
+        />
+      )}
+    </>
+  ) : null;
+};

package/src/components/{BaseGallery/CarouselBase → CarouselBase}/constants.ts

@@ -17,4 +17,8 @@ export const SLIDES_MANAGER_STATE: SlidesManagerState = {
   loopPoints: [],
   contentSize: 0,
   snaps: [],
+  containerWidth: 0,
+  layerWidth: 0,
+  min: 0,
+  max: 0,
 };