@cloud-ru/ds-scroll 1.0.0

package/src/Scroll.tsx

@@ -0,0 +1,240 @@
+import 'overlayscrollbars/styles/overlayscrollbars.css';
+
+import { isBrowser, useLayoutEffect, WithSupportProps } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import { OverlayScrollbars } from 'overlayscrollbars';
+import { OverlayScrollbarsComponent, OverlayScrollbarsComponentRef } from 'overlayscrollbars-react';
+import { forwardRef, PropsWithChildren, useCallback, useImperativeHandle, useRef, useState } from 'react';
+
+import {
+  AUTOSCROLL_ENABLE_LIMIT,
+  AUTOSCROLL_TO,
+  BAR_AUTO_HIDE_DELAY_MS,
+  BAR_HIDE_STRATEGY,
+  RESIZE,
+  SIZE,
+} from './constants';
+import styles from './styles.module.scss';
+import { AutoscrollTo, BarHideStrategy, Resize, Size } from './types';
+
+export type ScrollProps = WithSupportProps<
+  PropsWithChildren<{
+    className?: string;
+    /** Размер скролбаров */
+    size?: Size;
+    /** Скролить ли по клику в скроллбар. */
+    clickScrolling?: boolean;
+    /**
+     * Включает автоскрол при маунте и изменении размера контента:
+     * <br /> - `bottom` - автоскрол вниз,
+     * <br /> - `right` - автоскрол вправо,
+     */
+    autoscrollTo?: AutoscrollTo;
+    /**
+     * Управление скрытием скролл баров:
+     * <br /> - `Never` - показывать всегда
+     * <br /> - `Leave` - скрывать когда курсор покидает компонент
+     * <br /> - `Scroll` - показывать только когда происходит скроллинг
+     * <br /> - `Move` - показывать при движении курсора над компонентом
+     */
+    barHideStrategy?: BarHideStrategy;
+    /** Колбек события скрола. */
+    onScroll?: (event?: Event) => void;
+    /**
+     * Настройка возможности регулировать Scroll-контейнер:
+     * <br /> - `None` - нельзя изменять размер
+     * <br /> - `Horizontal` - можно изменять размер только по горизонтали
+     * <br /> - `Vertical` - можно изменять размер только по вертикали
+     * <br /> - `Both` - можно изменять размер в обеих координатах
+     */
+    resize?: Resize;
+    /** Отключает возможность взаимодействовать со скролбарами мышью. */
+    untouchableScrollbars?: boolean;
+    /** Должны ли паддинги быть абсолютными */
+    paddingAbsolute?: boolean;
+    /**
+     * Поведение overflow по осям. По умолчанию OverlayScrollbars выставляет `scroll`
+     * на обе оси; если контента по оси быть не должно — передавай `'hidden'`.
+     */
+    overflow?: {
+      x?: 'hidden' | 'visible' | 'scroll' | 'visible-hidden' | 'visible-scroll';
+      y?: 'hidden' | 'visible' | 'scroll' | 'visible-hidden' | 'visible-scroll';
+    };
+    /** Коллбэк вызывающийся на инициализацию скролла */
+    onInitialized?(): void;
+  }>
+>;
+
+type PositionsRef = {
+  scrolledToRight: boolean;
+  scrolledToBottom: boolean;
+};
+
+/**
+ * Установить nonce атрибут для инлайн стилей.
+ * @function setNonce
+ */
+export const setNonce = OverlayScrollbars.nonce;
+
+/**
+ * Scroll — контейнер с кастомными скроллбарами (OverlayScrollbars).
+ * Стили из @cloud-ru/ds-figma-variables (anatomy container + slider + theme colors).
+ */
+export const Scroll = forwardRef<HTMLElement, ScrollProps>(function Scroll(
+  {
+    children,
+    className,
+    onScroll: onScrollProp,
+    onInitialized: onInitializedProp,
+    size = SIZE.M,
+    resize = RESIZE.None,
+    clickScrolling = true,
+    barHideStrategy = BAR_HIDE_STRATEGY.Leave,
+    autoscrollTo,
+    paddingAbsolute,
+    overflow,
+    untouchableScrollbars = false,
+    ...rest
+  },
+  ref,
+) {
+  const overlayScrollbarsRef = useRef<OverlayScrollbarsComponentRef | null>(null);
+  const [isOverlayScrollbarInited, setOverlayScrollbarInited] = useState(false);
+  const getOSInstance = useCallback(
+    (overlayScrollbars = overlayScrollbarsRef.current) => overlayScrollbars?.osInstance(),
+    [overlayScrollbarsRef],
+  );
+
+  useImperativeHandle<HTMLElement | null, HTMLElement | null>(
+    ref,
+    () => (overlayScrollbarsRef.current?.osInstance()?.elements().viewport ?? null) as HTMLElement | null,
+  );
+
+  const lastPositionsRef = useRef<PositionsRef>({ scrolledToBottom: false, scrolledToRight: false });
+
+  const syncPositions = useCallback(
+    (scrollbars?: OverlayScrollbarsComponentRef | null) => {
+      const instance = getOSInstance(scrollbars);
+      if (instance) {
+        const { viewport } = instance.elements();
+        const gapToBottom = viewport.scrollHeight - (viewport.offsetHeight + viewport.scrollTop);
+        const gapToRight = viewport.scrollWidth - (viewport.offsetWidth + viewport.scrollLeft);
+        const hasYScroll = viewport.scrollHeight > viewport.offsetHeight;
+        const hasXScroll = viewport.scrollWidth > viewport.offsetWidth;
+        lastPositionsRef.current.scrolledToBottom = gapToBottom < AUTOSCROLL_ENABLE_LIMIT || !hasYScroll;
+        lastPositionsRef.current.scrolledToRight = gapToRight < AUTOSCROLL_ENABLE_LIMIT || !hasXScroll;
+      }
+    },
+    [getOSInstance],
+  );
+
+  useLayoutEffect(() => {
+    if (!autoscrollTo) {
+      onInitializedProp?.();
+      return;
+    }
+
+    const instance = getOSInstance();
+    if (instance && isOverlayScrollbarInited) {
+      syncPositions();
+
+      const { content } = instance.elements();
+
+      autoscrollTo === AUTOSCROLL_TO.Bottom && content.scroll(0, content.scrollHeight);
+      autoscrollTo === AUTOSCROLL_TO.Right && content.scroll(content.scrollWidth, 0);
+    }
+
+    onInitializedProp?.();
+
+    /* autoscrollTo умышленно не в депсах — интересен только на момент маунта */
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [getOSInstance, isOverlayScrollbarInited, syncPositions]);
+
+  const injectStateLayers = useCallback(() => {
+    const instance = overlayScrollbarsRef.current?.osInstance();
+    const host = instance?.elements().host;
+    if (!host) {
+      return;
+    }
+
+    host.querySelectorAll('.os-scrollbar-handle').forEach((handle: Element) => {
+      const stateLayerClass = styles.stateLayer ?? '';
+      if (!stateLayerClass) return;
+      if (handle.querySelector(`.${CSS.escape(stateLayerClass)}`)) {
+        return;
+      }
+
+      if (isBrowser()) {
+        const layer = document.createElement('div');
+        layer.classList.add(stateLayerClass);
+        layer.setAttribute('data-state', 'versionOnColor');
+        handle.appendChild(layer);
+      }
+    });
+  }, []);
+
+  const onInitialized = useCallback(() => {
+    injectStateLayers();
+    setOverlayScrollbarInited(true);
+  }, [injectStateLayers]);
+
+  const onScroll = useCallback(
+    (event?: Event) => {
+      onScrollProp?.(event);
+
+      if (autoscrollTo) {
+        syncPositions();
+      }
+    },
+    /* autoscrollTo не аффектит на расчеты в syncPositions */
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [onScrollProp, syncPositions],
+  );
+
+  const onContentSizeChanged = useCallback(() => {
+    if (!autoscrollTo) return;
+
+    const instance = getOSInstance()?.elements();
+
+    if (instance?.content) {
+      if (lastPositionsRef.current.scrolledToBottom && autoscrollTo === AUTOSCROLL_TO.Bottom) {
+        instance?.content.scroll(0, instance?.content.scrollHeight);
+      }
+      if (lastPositionsRef.current.scrolledToRight && autoscrollTo === AUTOSCROLL_TO.Right) {
+        instance?.content.scroll(instance?.content.scrollWidth, 0);
+      }
+    }
+  }, [getOSInstance, autoscrollTo]);
+
+  return (
+    <OverlayScrollbarsComponent
+      {...rest}
+      ref={overlayScrollbarsRef}
+      data-size={size}
+      data-untouchable-scrollbars={untouchableScrollbars || undefined}
+      className={cn(className, styles.scroll, 'osThemeSnack')}
+      style={{ resize }}
+      options={{
+        paddingAbsolute,
+        overflow,
+        scrollbars: {
+          autoHide: barHideStrategy,
+          autoHideDelay: BAR_AUTO_HIDE_DELAY_MS,
+          clickScroll: clickScrolling,
+        },
+      }}
+      events={{
+        initialized: onInitialized,
+        scroll: (_instance, event) => {
+          onScroll(event);
+        },
+        updated: () => {
+          injectStateLayers();
+          onContentSizeChanged();
+        },
+      }}
+    >
+      {autoscrollTo ? isOverlayScrollbarInited && children : children}
+    </OverlayScrollbarsComponent>
+  );
+});

package/src/constants.ts

@@ -0,0 +1,30 @@
+export const SIZE = {
+  S: 's',
+  M: 'm',
+} as const;
+
+export const BAR_HIDE_STRATEGY = {
+  Never: 'never',
+  Leave: 'leave',
+  Scroll: 'scroll',
+  Move: 'move',
+} as const;
+
+export const RESIZE = {
+  None: 'none',
+  Horizontal: 'horizontal',
+  Vertical: 'vertical',
+  Both: 'both',
+} as const;
+
+export const AUTOSCROLL_TO = {
+  Bottom: 'bottom',
+  Right: 'right',
+} as const;
+
+export const BAR_AUTO_HIDE_DELAY_MS = 100;
+
+/*
+ * Значение отступа до края контейнера при котором считается что контейнер проскролен до конца вниз или вправо, в пикселях.
+ */
+export const AUTOSCROLL_ENABLE_LIMIT = 2;

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Scroll, setNonce } from './Scroll';
+export type { ScrollProps } from './Scroll';
+export {
+  SIZE,
+  BAR_HIDE_STRATEGY,
+  RESIZE,
+  AUTOSCROLL_TO,
+  BAR_AUTO_HIDE_DELAY_MS,
+  AUTOSCROLL_ENABLE_LIMIT,
+} from './constants';
+export type { Size, BarHideStrategy, Resize, AutoscrollTo } from './types';

package/src/styles.module.scss

@@ -0,0 +1,163 @@
+/**
+ * Стили Scroll (OverlayScrollbars) в соответствии с Figma.
+ * Темизация через :global .osThemeSnack, токены из @cloud-ru/ds-figma-variables.
+ */
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/scroll.module' as scroll;
+@use '@cloud-ru/ds-materials' as m;
+
+$orientations: 'vertical', 'horizontal';
+$sizes: 's', 'm';
+/* stylelint-disable-next-line */
+$theme-name: osThemeSnack;
+$scrollbar-slider-active-zone: 12px;
+
+.scroll {
+  position: relative;
+  /* stylelint-disable-next-line declaration-property-value-allowed-list */
+  z-index: 0;
+
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+}
+
+.stateLayer {
+  visibility: initial;
+}
+
+/**
+ * Темизация OverlayScrollbars: селекторы из документации библиотеки.
+ * Размеры и цвета — из @cloud-ru/ds-figma-variables (scroll anatomy + theme).
+ */
+/* stylelint-disable-next-line selector-pseudo-class-no-unknown */
+:global {
+  /* ——— Базовые скроллбары ——— */
+  .#{$theme-name} .os-scrollbar {
+    padding: 0;
+  }
+
+  @each $orientation in $orientations {
+    .#{$theme-name}[data-untouchable-scrollbars] > .os-scrollbar-#{$orientation} {
+      pointer-events: none;
+
+      > .os-scrollbar-track {
+        pointer-events: none;
+
+        > .os-scrollbar-handle {
+          pointer-events: none;
+        }
+      }
+    }
+  }
+
+  /* ——— Размеры (s/m) и resize-disabled ——— */
+  @each $size in $sizes {
+    @each $orientation in $orientations {
+      .#{$theme-name}[data-size='#{$size}'] > .os-scrollbar-#{$orientation} {
+        @if $orientation == 'vertical' {
+          width: scroll.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', $size, 'width');
+        }
+
+        @else {
+          height: scroll.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', $size, 'height');
+        }
+
+        pointer-events: none;
+        overflow: hidden;
+
+        // По макету у скролла нет жёлоба-рельсы — виден только handle (thumb)
+        // c neutral-decorTransparent (стилизуется ниже). Трек остаётся прозрачным.
+        & > .os-scrollbar-track > .os-scrollbar-handle {
+          border-radius: scroll.simple-var(scroll.$scroll, 'anatomy', 'slider', 'size', $size, 'border-radius');
+
+          @if $orientation == 'vertical' {
+            width: scroll.simple-var(scroll.$scroll, 'anatomy', 'slider', 'size', $size, 'width');
+          }
+
+          @else {
+            height: scroll.simple-var(scroll.$scroll, 'anatomy', 'slider', 'size', $size, 'height');
+          }
+        }
+      }
+    }
+
+    .#{$theme-name}[data-size='#{$size}'].os-host-resize-disabled > .os-scrollbar-horizontal {
+      right: scroll.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', $size, 'width');
+    }
+    .#{$theme-name}[data-size='#{$size}'].os-host-resize-disabled.os-host-rtl > .os-scrollbar-horizontal {
+      right: 0;
+      left: scroll.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', $size, 'width');
+    }
+    .#{$theme-name}[data-size='#{$size}'].os-host-resize-disabled > .os-scrollbar-vertical {
+      bottom: scroll.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', $size, 'height');
+    }
+  }
+
+  // TODO: кажется, это не используется, и у нас применяется нативный ресайз
+
+  /* ——— Corner (resize grip) ——— */
+
+  /* .#{$theme-name} > .os-scrollbar-corner {
+   --bg-icon-mask: url('data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0iYmxhY2siIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJNMTMuNTMwMyAzLjQ2OTY3QzEzLjgyMzIgMy43NjI1NiAxMy44MjMyIDQuMjM3NDQgMTMuNTMwMyA0LjUzMDMzTDQuNTMwMzMgMTMuNTMwM0M0LjIzNzQ0IDEzLjgyMzIgMy43NjI1NiAxMy44MjMyIDMuNDY5NjcgMTMuNTMwM0MzLjE3Njc4IDEzLjIzNzQgMy4xNzY3OCAxMi43NjI2IDMuNDY5NjcgMTIuNDY5N0wxMi40Njk3IDMuNDY5NjdDMTIuNzYyNiAzLjE3Njc4IDEzLjIzNzQgMy4xNzY3OCAxMy41MzAzIDMuNDY5NjdaTTEzLjUzMDMgNy40Njk2N0MxMy44MjMyIDcuNzYyNTYgMTMuODIzMiA4LjIzNzQ0IDEzLjUzMDMgOC41MzAzM0w4LjUzMDMzIDEzLjUzMDNDOC4yMzc0NCAxMy44MjMyIDcuNzYyNTYgMTMuODIzMiA3LjQ2OTY3IDEzLjUzMDNDNy4xNzY3OCAxMy4yMzc0IDcuMTc2NzggMTIuNzYyNiA3LjQ2OTY3IDEyLjQ2OTdMMTIuNDY5NyA3LjQ2OTY3QzEyLjc2MjYgNy4xNzY3OCAxMy4yMzc0IDcuMTc2NzggMTMuNTMwMyA3LjQ2OTY3Wk0xMy41MzAzIDEyLjUzMDNDMTMuODIzMiAxMi4yMzc0IDEzLjgyMzIgMTEuNzYyNiAxMy41MzAzIDExLjQ2OTdDMTMuMjM3NCAxMS4xNzY4IDEyLjc2MjYgMTEuMTc2OCAxMi40Njk3IDExLjQ2OTdMMTEuNDY5NyAxMi40Njk3QzExLjE3NjggMTIuNzYyNiAxMS4xNzY4IDEzLjIzNzQgMTEuNDY5NyAxMy41MzAzQzExLjc2MjYgMTMuODIzMiAxMi4yMzc0IDEzLjgyMzIgMTIuNTMwMyAxMy41MzAzTDEzLjUzMDMgMTIuNTMwM1oiIGZpbGw9ImJsYWNrIi8+Cjwvc3ZnPgo=');
+   z-index: 0;
+  
+   width: scroll.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', 'm', 'width');
+   height: scroll.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', 'm', 'height');
+  
+   background-color: base.simple-var(base.$sn-theme, 'color', 'neutral', 'decor');
+   background-image: unset;
+  
+   mask-image: var(--bg-icon-mask);
+  
+   &:hover {
+     background-color: base.simple-var(base.$sn-theme, 'color', 'neutral', 'text');
+   }
+  }
+  
+  .os-dragging .#{$theme-name} > .os-scrollbar-corner:hover {
+   background-color: base.simple-var(base.$sn-theme, 'color', 'primary', 'accent');
+  }
+  .#{$theme-name}.os-host-resize-disabled > .os-scrollbar-corner {
+   display: none;
+  } */
+}
+
+/*
+ * Handle + state layer: нельзя держать внутри `:global { }` — иначе класс из `#{stateLayer}`
+ * станет глобальным и не совпадёт с хэшем из JS. Родитель — только :global(цепочка).
+ */
+@each $orientation in $orientations {
+  :global(.#{$theme-name} > .os-scrollbar-#{$orientation} > .os-scrollbar-track > .os-scrollbar-handle) {
+    pointer-events: initial;
+    position: relative;
+    border: base.$sn-primitive-strokeWeight-strokeThin solid base.$sn-theme-color-invertNeutral-decorTransparent;
+    background: base.$sn-theme-color-neutral-decorTransparent;
+
+    .#{stateLayer} {
+      transition: background 0.15s;
+    }
+
+    @include m.has-state-layer-as-child(#{stateLayer});
+
+    @if $orientation == 'vertical' {
+      left: 50%;
+      translate: -50% 0;
+
+      &::before {
+        right: -$scrollbar-slider-active-zone;
+        left: -$scrollbar-slider-active-zone;
+      }
+    }
+
+    @else {
+      top: 50%;
+      translate: 0 -50%;
+
+      &::before {
+        top: -$scrollbar-slider-active-zone;
+        bottom: -$scrollbar-slider-active-zone;
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,11 @@
+import { ValueOf } from '@cloud-ru/ds-utils';
+
+import { AUTOSCROLL_TO, BAR_HIDE_STRATEGY, RESIZE, SIZE } from './constants';
+
+export type Size = ValueOf<typeof SIZE>;
+
+export type AutoscrollTo = ValueOf<typeof AUTOSCROLL_TO>;
+
+export type Resize = ValueOf<typeof RESIZE>;
+
+export type BarHideStrategy = ValueOf<typeof BAR_HIDE_STRATEGY>;