@vkontakte/vkui 4.28.0 → 4.28.1

package/src/components/Touch/Readme.md

@@ -0,0 +1,116 @@
+Touch – это компонент для удобной работы с pointer событиями, такими как клик, тап, перетаскивание и т.д.
+Он инкапсулирует в себе логику обработки вышеперечисленных событий, дает возможность отдельно реагировать на движение
+пальца (или мышки) по осям X и Y, а так же предоставляет данные о геометрии жеста.
+
+Компонент используется во многих других компонентах библиотеки (Cell, Slider, Gallery, Tappable).
+
+```jsx
+const circleStyle = {
+  width: 40,
+  height: 40,
+  borderRadius: "50%",
+  background: "var(--accent)",
+  position: "absolute",
+  left: "50%",
+  top: "50%",
+  marginLeft: -20,
+  marginTop: -20,
+};
+
+const containerStyle = {
+  height: 200,
+  border: "8px solid var(--icon_secondary)",
+  position: "relative",
+};
+
+class Example extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.state = {
+      shiftX: 0,
+      shiftY: 0,
+    };
+
+    this.startX = 0;
+    this.startY = 0;
+
+    this.onMove = this.onMove.bind(this);
+    this.onEnd = this.onEnd.bind(this);
+    this.getCircleRef = this.getCircleRef.bind(this);
+  }
+
+  componentDidMount() {
+    this.limitX = this.circleRef.offsetLeft;
+    this.limitY = this.circleRef.offsetTop;
+  }
+
+  onMove(e) {
+    let shiftX = this.startX + e.shiftX;
+    let shiftY = this.startY + e.shiftY;
+
+    this.setState({
+      shiftX:
+        shiftX > this.limitX
+          ? this.limitX
+          : shiftX < -this.limitX
+          ? -this.limitX
+          : shiftX,
+      shiftY:
+        shiftY > this.limitY
+          ? this.limitY
+          : shiftY < -this.limitY
+          ? -this.limitY
+          : shiftY,
+    });
+  }
+
+  onEnd(e) {
+    this.startX += e.shiftX;
+    this.startY += e.shiftY;
+  }
+
+  getCircleRef(el) {
+    this.circleRef = el;
+  }
+
+  get limitExceeded() {
+    const { shiftX, shiftY } = this.state;
+    return Math.abs(shiftX) >= this.limitX || Math.abs(shiftY) >= this.limitY;
+  }
+
+  render() {
+    const { shiftX, shiftY, limitExceeded } = this.state;
+
+    return (
+      <View activePanel="gallery">
+        <Panel id="gallery">
+          <PanelHeader>Touch</PanelHeader>
+          <Group header={<Header mode="secondary">Перетащите кружок</Header>}>
+            <div
+              style={{
+                ...containerStyle,
+                borderColor: this.limitExceeded
+                  ? "var(--destructive)"
+                  : "var(--icon_secondary)",
+              }}
+            >
+              <Touch
+                getRootRef={this.getCircleRef}
+                onMove={this.onMove}
+                onEnd={this.onEnd}
+                style={{
+                  ...circleStyle,
+                  transform: `translate(${shiftX}px, ${shiftY}px)`,
+                }}
+              />
+            </div>
+          </Group>
+        </Panel>
+      </View>
+    );
+  }
+}
+
+<Example />;
+```

package/src/components/Touch/Touch.tsx

@@ -0,0 +1,285 @@
+import * as React from "react";
+import {
+  getSupportedEvents,
+  coordX,
+  coordY,
+  touchEnabled,
+  VKUITouchEvent,
+} from "../../lib/touch";
+import { HasComponent, HasRootRef } from "../../types";
+import { useDOM } from "../../lib/dom";
+import { useExternRef } from "../../hooks/useExternRef";
+import { useEventListener } from "../../hooks/useEventListener";
+import { useIsomorphicLayoutEffect } from "../../lib/useIsomorphicLayoutEffect";
+
+export interface TouchProps
+  extends React.AllHTMLAttributes<HTMLElement>,
+    HasRootRef<HTMLElement>,
+    HasComponent {
+  /**
+   * Привязать onEnter и onLeave через pointer-events - работает на disabled-инпутах
+   */
+  usePointerHover?: boolean;
+  useCapture?: boolean;
+  slideThreshold?: number;
+  noSlideClick?: boolean;
+  onEnter?: HoverHandler;
+  onLeave?: HoverHandler;
+  onStart?: TouchEventHandler;
+  onStartX?: TouchEventHandler;
+  onStartY?: TouchEventHandler;
+  onMove?: TouchEventHandler;
+  onMoveX?: TouchEventHandler;
+  onMoveY?: TouchEventHandler;
+  onEnd?: TouchEventHandler;
+  onEndX?: TouchEventHandler;
+  onEndY?: TouchEventHandler;
+  stopPropagation?: boolean;
+}
+
+export interface Gesture {
+  startX: number;
+  startY: number;
+  startT: Date;
+  duration: number;
+  isPressed: boolean;
+  isY: boolean;
+  isX: boolean;
+  isSlideX: boolean;
+  isSlideY: boolean;
+  isSlide: boolean;
+  shiftX: number;
+  shiftY: number;
+  shiftXAbs: number;
+  shiftYAbs: number;
+}
+
+export interface TouchEvent extends Gesture {
+  originalEvent: VKUITouchEvent;
+}
+
+type HoverHandler = (outputEvent: MouseEvent) => void;
+export type TouchEventHandler = (e: TouchEvent) => void;
+export type ClickHandler = (e: React.MouseEvent<HTMLElement>) => void;
+export type DragHandler = (e: React.DragEvent<HTMLElement>) => void;
+
+export const Touch: React.FC<TouchProps> = ({
+  onStart,
+  onStartX,
+  onStartY,
+  onMove: _onMove,
+  onMoveX,
+  onMoveY,
+  onLeave,
+  onEnter,
+  onEnd: _onEnd,
+  onEndX,
+  onEndY,
+  onClickCapture,
+  usePointerHover,
+  slideThreshold = 5,
+  useCapture = false,
+  Component = "div",
+  getRootRef,
+  noSlideClick = false,
+  stopPropagation = false,
+  ...restProps
+}: TouchProps) => {
+  const { document } = useDOM();
+  const events = React.useMemo(getSupportedEvents, []);
+  const didSlide = React.useRef(false);
+  const gesture = React.useRef<Partial<Gesture> | null>(null);
+  const handle = (
+    e: VKUITouchEvent,
+    handers: Array<TouchEventHandler | undefined | false>
+  ) => {
+    stopPropagation && e.stopPropagation();
+    handers.forEach((cb) => {
+      const duration = Date.now() - (gesture.current?.startT?.getTime() ?? 0);
+      cb && cb({ ...(gesture.current as Gesture), duration, originalEvent: e });
+    });
+  };
+
+  const enterHandler = useEventListener(
+    usePointerHover ? "pointerenter" : "mouseenter",
+    onEnter
+  );
+  const leaveHandler = useEventListener(
+    usePointerHover ? "pointerleave" : "mouseleave",
+    onLeave
+  );
+  const startHandler = useEventListener(
+    events[0],
+    (e: VKUITouchEvent) => {
+      gesture.current = initGesture(coordX(e), coordY(e));
+
+      handle(e, [onStart, onStartX, onStartY]);
+      // 1 line, 2 bad specs, 2 workarounds:
+      subscribe(
+        touchEnabled()
+          ? // Touch events fire on initial target, and won't bubble if its removed
+            // see: #235, #1968, https://stackoverflow.com/a/45760014
+            (e.target as HTMLElement)
+          : // Mouse events fire on the element under pointer, so we lose move / end
+            // if pointer goes outside container.
+            // Can be fixed by PointerEvents' setPointerCapture later
+            document
+      );
+    },
+    { capture: useCapture, passive: false }
+  );
+  const containerRef = useExternRef(getRootRef);
+
+  useIsomorphicLayoutEffect(() => {
+    const el = containerRef.current;
+    if (el) {
+      enterHandler.add(el);
+      leaveHandler.add(el);
+      startHandler.add(el);
+    }
+  }, [Component]);
+
+  function onMove(e: VKUITouchEvent) {
+    const {
+      isPressed,
+      isX,
+      isY,
+      startX = 0,
+      startY = 0,
+    } = gesture.current ?? {};
+
+    if (isPressed) {
+      // смещения
+      const shiftX = coordX(e) - startX;
+      const shiftY = coordY(e) - startY;
+
+      // абсолютные значения смещений
+      const shiftXAbs = Math.abs(shiftX);
+      const shiftYAbs = Math.abs(shiftY);
+
+      // Если определяем мультитач, то прерываем жест
+      if (!!e.touches && e.touches.length > 1) {
+        return onEnd(e);
+      }
+
+      // если мы ещё не определились
+      if (!isX && !isY) {
+        const willBeX = shiftXAbs >= slideThreshold && shiftXAbs > shiftYAbs;
+        const willBeY = shiftYAbs >= slideThreshold && shiftYAbs > shiftXAbs;
+        const willBeSlidedX = willBeX && (!!onMoveX || !!_onMove);
+        const willBeSlidedY = willBeY && (!!onMoveY || !!_onMove);
+
+        Object.assign(gesture.current, {
+          isY: willBeY,
+          isX: willBeX,
+          isSlideX: willBeSlidedX,
+          isSlideY: willBeSlidedY,
+          isSlide: willBeSlidedX || willBeSlidedY,
+        });
+      }
+
+      if (gesture.current?.isSlide) {
+        Object.assign(gesture.current, {
+          shiftX,
+          shiftY,
+          shiftXAbs,
+          shiftYAbs,
+        });
+
+        handle(e, [
+          _onMove,
+          gesture.current.isSlideX && onMoveX,
+          gesture.current.isSlideY && onMoveY,
+        ]);
+      }
+    }
+  }
+
+  function onEnd(e: VKUITouchEvent) {
+    const { isPressed, isSlide, isSlideX, isSlideY } = gesture.current ?? {};
+
+    if (isPressed) {
+      handle(e, [_onEnd, isSlideY && onEndY, isSlideX && onEndX]);
+    }
+
+    didSlide.current = Boolean(isSlide);
+    gesture.current = {};
+
+    // Если это был тач-евент, симулируем отмену hover
+    if (touchEnabled()) {
+      onLeave && onLeave(e);
+    }
+    subscribe(null);
+  }
+
+  const listenerParams = { capture: useCapture, passive: false };
+  const listeners = [
+    useEventListener(events[1], onMove, listenerParams),
+    useEventListener(events[2], onEnd, listenerParams),
+    useEventListener(events[3], onEnd, listenerParams),
+  ];
+  function subscribe(el: HTMLElement | Document | null | undefined) {
+    if (el) {
+      listeners.forEach((l) => l.add(el));
+    }
+  }
+
+  /**
+   * Обработчик событий dragstart
+   * Отменяет нативное браузерное поведение для вложенных ссылок и изображений
+   */
+  const onDragStart = (e: React.DragEvent<HTMLElement>) => {
+    const target = e.target as HTMLElement;
+    if (target.tagName === "A" || target.tagName === "IMG") {
+      e.preventDefault();
+    }
+  };
+
+  /**
+   * Обработчик клика по компоненту
+   * Отменяет переход по вложенной ссылке, если был зафиксирован свайп
+   */
+  const postGestureClick: typeof onClickCapture = (e) => {
+    if (!didSlide.current) {
+      return onClickCapture && onClickCapture(e);
+    }
+    // eslint-disable-next-line no-restricted-properties
+    if ((e.target as HTMLElement).closest("a")) {
+      e.preventDefault();
+    }
+    if (noSlideClick) {
+      e.stopPropagation();
+    } else {
+      onClickCapture && onClickCapture(e);
+    }
+    didSlide.current = false;
+  };
+
+  return (
+    <Component
+      {...restProps}
+      onDragStart={onDragStart}
+      onClickCapture={postGestureClick}
+      ref={containerRef}
+    />
+  );
+};
+
+function initGesture(startX: number, startY: number): Gesture {
+  return {
+    startX,
+    startY,
+    startT: new Date(),
+    duration: 0,
+    isPressed: true,
+    isY: false,
+    isX: false,
+    isSlideX: false,
+    isSlideY: false,
+    isSlide: false,
+    shiftX: 0,
+    shiftY: 0,
+    shiftXAbs: 0,
+    shiftYAbs: 0,
+  };
+}

package/src/components/Touch/TouchContext.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+
+/**
+ * Контекст для компонентов, использующих Touch в качестве корневой обёртки,
+ * и для которых важно не предотвращать вспылие тач-событий от дочерних компонентов
+ */
+const TouchRootContext: React.Context<boolean> =
+  React.createContext<boolean>(false);
+
+// eslint-disable-next-line import/no-default-export
+export default TouchRootContext;

package/src/components/Typography/Caption/Caption.css

@@ -0,0 +1,97 @@
+/*
+ * В следующей версии библиотеки Caption 1 должен превратиться в Footnote, Caption 2 — в Caption 1 и так далее.
+ * В токенах это обновление уже есть.
+ * TODO переехать на новый нейминг в 5.0.0. Заменить Caption 1 на Footnote, а остальные Caption поднять на один уровень наверх.
+ */
+
+.Caption {
+  display: block;
+  margin: 0;
+}
+
+.Caption--caps {
+  text-transform: uppercase;
+}
+
+.Caption--l-1 {
+  font-size: var(--vkui--font_footnote--font_size--regular);
+  line-height: var(--vkui--font_footnote--line_height--regular);
+  font-weight: var(--vkui--font_footnote--font_weight--regular);
+}
+
+.Caption--l-1.Caption--caps {
+  font-size: var(--vkui--font_footnote_caps--font_size--regular);
+  line-height: var(--vkui--font_footnote_caps--line_height--regular);
+  font-weight: var(--vkui--font_footnote_caps--font_weight--regular);
+}
+
+.Caption--l-2 {
+  font-size: var(--vkui--font_caption1--font_size--regular);
+  line-height: var(--vkui--font_caption1--line_height--regular);
+  font-weight: var(--vkui--font_caption1--font_weight--regular);
+}
+
+.Caption--l-2.Caption--caps {
+  font-size: var(--vkui--font_caption1_caps--font_size--regular);
+  line-height: var(--vkui--font_caption1_caps--line_height--regular);
+  font-weight: var(--vkui--font_caption1_caps--font_weight--regular);
+}
+
+.Caption--l-3 {
+  font-size: var(--vkui--font_caption2--font_size--regular);
+  line-height: var(--vkui--font_caption2--line_height--regular);
+  font-weight: var(--vkui--font_caption2--font_weight--regular);
+}
+
+.Caption--l-3.Caption--caps {
+  font-size: var(--vkui--font_caption2_caps--font_size--regular);
+  line-height: var(--vkui--font_caption2_caps--line_height--regular);
+  font-weight: var(--vkui--font_caption2_caps--font_weight--regular);
+}
+
+.Caption--l-4 {
+  font-size: var(--vkui--font_caption3--font_size--regular);
+  line-height: var(--vkui--font_caption3--line_height--regular);
+  font-weight: var(--vkui--font_caption3--font_weight--regular);
+}
+
+.Caption--l-4.Caption--caps {
+  font-size: var(--vkui--font_caption3_caps--font_size--regular);
+  line-height: var(--vkui--font_caption3_caps--line_height--regular);
+  font-weight: var(--vkui--font_caption3_caps--font_weight--regular);
+}
+
+.Caption.Caption--w-1 {
+  /* Мы утяжеляем селеткор, чтобы перебить селекторы .Caption--caps */
+  font-weight: var(--vkui--font_weight_accent1);
+}
+
+.Caption.Caption--w-2 {
+  /* Мы утяжеляем селеткор, чтобы перебить селекторы .Caption--caps */
+  font-weight: var(--vkui--font_weight_accent2);
+}
+
+.Caption.Caption--w-3 {
+  /* Мы утяжеляем селеткор, чтобы перебить селекторы .Caption--caps */
+  font-weight: var(--vkui--font_weight_accent3);
+}
+
+/* TODO удалить перед релизом 5.0.0 */
+.Caption--w-regular {
+  font-weight: 400;
+}
+
+/* TODO удалить перед релизом 5.0.0 */
+.Caption--w-medium {
+  font-weight: 500;
+}
+
+/* TODO удалить перед релизом 5.0.0 */
+.Caption--w-semibold {
+  font-weight: 600;
+}
+
+/* TODO удалить перед релизом 5.0.0 */
+.Caption--w-bold {
+  font-weight: 700;
+}

package/src/components/Typography/Caption/Caption.tsx

@@ -0,0 +1,53 @@
+import * as React from "react";
+import { HasComponent } from "../../../types";
+import { classNames } from "../../../lib/classNames";
+import { warnOnce } from "../../../lib/warnOnce";
+import "./Caption.css";
+
+export interface CaptionProps
+  extends React.AllHTMLAttributes<HTMLElement>,
+    HasComponent {
+  /**
+   * Задаёт начертание шрифта отличное от стандартного.
+   *
+   * > ⚠️ Начертания `"bold"`, `"semibold"`, `medium` и `"regular"` устарели и будут удалены в 5.0.0. Используйте значения `"1"`, `"2"` и `"3"`.
+   */
+  weight?: "regular" | "medium" | "semibold" | "bold" | "1" | "2" | "3";
+  level?: "1" | "2" | "3" | "4";
+  caps?: boolean;
+}
+
+const warn = warnOnce("Caption");
+
+export const Caption: React.FC<CaptionProps> = ({
+  children,
+  weight,
+  level = "1",
+  caps,
+  Component = "span",
+  ...restProps
+}: CaptionProps) => {
+  if (process.env.NODE_ENV === "development") {
+    if (
+      weight &&
+      ["heavy", "bold", "semibold", "medium", "regular"].includes(weight)
+    )
+      warn(
+        `Начертание weight="${weight}" устарело и будет удалено в 5.0.0. Используйте значения "1", "2" и "3"`
+      );
+  }
+
+  return (
+    <Component
+      {...restProps}
+      vkuiClass={classNames(
+        "Caption",
+        `Caption--l-${level}`,
+        caps && "Caption--caps",
+        weight && `Caption--w-${weight}`
+      )}
+    >
+      {children}
+    </Component>
+  );
+};

package/src/components/Typography/Caption/Readme.md

@@ -0,0 +1,29 @@
+```jsx { "props": { "layout": false, "iframe": false } }
+<div style={{ padding: 20 }}>
+  <Caption level="1" style={{ marginBottom: 16 }}>
+    Caption 1
+  </Caption>
+  <Caption level="2" style={{ marginBottom: 16 }}>
+    Caption 2
+  </Caption>
+  <Caption level="3">Caption 3</Caption>
+</div>
+```
+
+## Кастомизация
+
+Есть возможность переопределить жирность.
+
+```jsx { "props": { "layout": false, "iframe": false } }
+<div style={{ padding: 20 }}>
+  <Caption level="1" weight="1" style={{ marginBottom: 16 }}>
+    Caption 1 weight 1
+  </Caption>
+  <Caption level="1" weight="2" style={{ marginBottom: 16 }}>
+    Caption 1 weight 2
+  </Caption>
+  <Caption level="1" weight="3">
+    Caption 1 weight 3
+  </Caption>
+</div>
+```

package/src/components/Typography/Headline/Headline.css

@@ -0,0 +1,25 @@
+.Headline {
+  display: block;
+  margin: 0;
+  font-size: 16px;
+  line-height: 20px;
+}
+
+.Headline--w-regular {
+  font-weight: 400;
+}
+
+.Headline--w-medium {
+  font-weight: 500;
+}
+
+.Headline--w-semibold {
+  font-weight: 600;
+}
+
+/**
+ * ANDROID
+ */
+.Headline--android.Headline--w-semibold {
+  font-weight: 500;
+}

package/src/components/Typography/Headline/Headline.tsx

@@ -0,0 +1,36 @@
+import * as React from "react";
+import { HasComponent } from "../../../types";
+import { usePlatform } from "../../../hooks/usePlatform";
+import { classNames } from "../../../lib/classNames";
+import { getClassName } from "../../../helpers/getClassName";
+import "./Headline.css";
+
+export interface HeadlineProps
+  extends React.AllHTMLAttributes<HTMLElement>,
+    HasComponent {
+  weight: "regular" | "medium" | "semibold";
+}
+
+const Headline: React.FC<HeadlineProps> = ({
+  children,
+  weight = "regular",
+  Component = "h3",
+  ...restProps
+}: HeadlineProps) => {
+  const platform = usePlatform();
+
+  return (
+    <Component
+      {...restProps}
+      vkuiClass={classNames(
+        getClassName("Headline", platform),
+        `Headline--w-${weight}`
+      )}
+    >
+      {children}
+    </Component>
+  );
+};
+
+// eslint-disable-next-line import/no-default-export
+export default Headline;

package/src/components/Typography/Headline/Readme.md

@@ -0,0 +1,24 @@
+Упрощения в Android-версии (происходят автоматически):
+
+- `semibold` превращается в `medium`
+
+```jsx
+<View activePanel="test">
+  <Panel id="test">
+    <PanelHeader>Headline</PanelHeader>
+    <Group>
+      <Div>
+        <Headline weight="regular" style={{ marginBottom: 16 }}>
+          Headline regular
+        </Headline>
+        <Headline weight="medium" style={{ marginBottom: 16 }}>
+          Headline medium
+        </Headline>
+        <Headline weight="semibold" style={{ marginBottom: 16 }}>
+          Headline semibold
+        </Headline>
+      </Div>
+    </Group>
+  </Panel>
+</View>
+```

package/src/components/Typography/Subhead/Readme.md

@@ -0,0 +1,21 @@
+```jsx { "props": { "layout": false, "iframe": false } }
+<div style={{ padding: 20 }}>
+  <Subhead>Subhead</Subhead>
+</div>
+```
+
+## Кастомизация
+
+Есть возможность переопределить жирность.
+
+```jsx { "props": { "layout": false, "iframe": false } }
+<div style={{ padding: 20 }}>
+  <Subhead weight="1" style={{ marginBottom: 16 }}>
+    Subhead weight 1
+  </Subhead>
+  <Subhead weight="2" style={{ marginBottom: 16 }}>
+    Subhead weight 2
+  </Subhead>
+  <Subhead weight="3">Subhead weight 3</Subhead>
+</div>
+```