@vkontakte/vkui 4.28.0 → 4.28.1

package/src/components/Tooltip/Readme.md

@@ -0,0 +1,263 @@
+`Tooltip` – это **экспериментальный** компонент для отрисовки подсказки, как правило в случаях, когда пользователю
+хочется представить новый функционал. Это достаточно сложный с точки зрения управления компонент, поэтому он
+требует подробной документации.
+
+Для показа тултипа по ховеру, воспользуйтесь [`RichTooltip`](#/RichTooltip) или [`TextTooltip`](#/TextTooltip).
+
+### Концепция
+
+Этот тултип служит для ознакомительных целей. То есть показывать его надо один раз, запоминая факт показа между
+сессиями. Рекомендуется показывать тултип сразу после того, как нуждающийся в нем элемент появился в зоне видимости.
+Это значит, что если, например, до элемента нужно скроллить, то показывать тултип нужно не сразу при попадании
+на страницу, а именно в момент, когда пользователь доскроллил до элемента.
+
+> **Важно**
+>
+> На странице не может быть два одновременно показанных тултипа. Они всегда должны показываться
+> последовательно: следующий показывается при закрытии текущего и так до конца.
+
+### API
+
+Если хочется снабдить какой-то элемент интерфейса подсказкой, достаточно просто «обернуть» его тултипом:
+
+```jsx static
+import { Tooltip, Button } from "@vkontakte/vkui";
+
+<Tooltip text="Обновлённый раздел поможет найти друзей">
+  <Button>Друзья</Button>
+</Tooltip>;
+```
+
+О возможностях тултипа можно прочитать в описании свойств и методов.
+
+```jsx
+class Example extends React.Component {
+  constructor() {
+    this.state = {
+      tooltip: true,
+      tooltip2: true,
+      tooltip3: false,
+      activePanel: "tooltip",
+    };
+  }
+
+  render() {
+    return (
+      <View activePanel={this.state.activePanel}>
+        <Panel id="tooltip">
+          <PanelHeader>Tooltip</PanelHeader>
+          <Group>
+            <List>
+              <Cell>Музыка</Cell>
+              <Cell>Видео</Cell>
+              <Cell>Игры</Cell>
+              <Cell>Закладки</Cell>
+              <Cell>Документы</Cell>
+              <Cell>Денежные переводы</Cell>
+            </List>
+          </Group>
+          <Group>
+            <Tooltip
+              mode="light"
+              text="У нас тут brand new функционал подвезли. Зацените!"
+              isShown={this.state.tooltip}
+              onClose={() => this.setState({ tooltip: false })}
+              offsetX={10}
+            >
+              <Cell onClick={() => this.setState({ activePanel: "tooltip2" })}>
+                VK Pay
+              </Cell>
+            </Tooltip>
+          </Group>
+        </Panel>
+
+        <Panel id="tooltip2">
+          <PanelHeader
+            left={
+              <PanelHeaderButton
+                onClick={() => this.setState({ activePanel: "tooltip" })}
+              >
+                {this.props.platform === ANDROID ||
+                this.props.platform === VKCOM ? (
+                  <Icon24Back />
+                ) : (
+                  <Icon28ChevronBack />
+                )}
+              </PanelHeaderButton>
+            }
+            right={
+              <PanelHeaderButton>
+                <Tooltip
+                  isShown={this.state.tooltip2}
+                  onClose={() =>
+                    this.setState({ tooltip2: false, tooltip3: true })
+                  }
+                  cornerOffset={-10}
+                  offsetX={7}
+                  text="Обновлённый раздел поможет найти друзей"
+                  header="Рекомендации друзей"
+                >
+                  <Icon24Add />
+                </Tooltip>
+              </PanelHeaderButton>
+            }
+          >
+            Tooltip
+          </PanelHeader>
+          <Group>
+            <List>
+              <Cell
+                before={
+                  <Tooltip
+                    text="Теперь у нас появились аватарки в списках. Правда круто?"
+                    isShown={this.state.tooltip3}
+                    onClose={() => this.setState({ tooltip3: false })}
+                    cornerOffset={-6}
+                  >
+                    <Avatar />
+                  </Tooltip>
+                }
+                description="Веб-сайт"
+              >
+                Команда ВКонтакте
+              </Cell>
+              <Cell before={<Avatar />} description="Музыкант">
+                Robbie Williams
+              </Cell>
+              <Cell before={<Avatar />} description="Издательский дом">
+                ПостНаука
+              </Cell>
+              <Cell before={<Avatar />} description="Издательский дом">
+                ПостНаука
+              </Cell>
+              <Cell before={<Avatar />} description="Издательский дом">
+                ПостНаука
+              </Cell>
+              <Cell before={<Avatar />} description="Издательский дом">
+                ПостНаука
+              </Cell>
+              <Cell before={<Avatar />} description="Издательский дом">
+                ПостНаука
+              </Cell>
+            </List>
+          </Group>
+        </Panel>
+      </View>
+    );
+  }
+}
+
+const ExampleWithPlatform = withPlatform(Example);
+
+<ExampleWithPlatform />;
+```
+
+## TooltipContainer
+
+Чтобы использовать тултип без `Panel` / `PanelHeader` / `FixedLayout`:
+
+- в скроллящемся контейнере — замените какой-нибудь элемент, внутри которого нет скролла, на `<TooltipContainer>` и добавьте ему `position: relative` (или другую не-static).
+- внутри `position: fixed` — `<TooltipContainer fixed>`
+
+```jsx { "props": { "layout": false, "frame": true } }
+<>
+  <TooltipContainer style={{ minHeight: "120vh" }}>
+    <Tooltip text="Я скроллюсь">
+      <div style={{ display: "inline-block" }}>
+        <Avatar />
+      </div>
+    </Tooltip>
+    <Tooltip text="Двигаем стрелочку" cornerOffset={20}>
+      <div style={{ display: "inline-block", marginLeft: 100 }}>
+        <Avatar />
+      </div>
+    </Tooltip>
+  </TooltipContainer>
+  <TooltipContainer
+    fixed
+    style={{
+      minHeight: "30px",
+      border: "1px solid",
+      margin: "100px 100px 0",
+      position: "relative",
+      background: "var(--background_content)",
+      zIndex: 1,
+    }}
+  >
+    <Tooltip text="Я вылезаю (fixed)">
+      <div style={{ display: "inline-block" }}>
+        <Avatar />
+      </div>
+    </Tooltip>
+  </TooltipContainer>
+  <TooltipContainer
+    style={{
+      minHeight: "100vh",
+      border: "1px solid",
+      margin: "64px 100px 100px",
+      position: "relative",
+      background: "var(--background_content)",
+      zIndex: 1,
+    }}
+  >
+    <Tooltip text="Я прилип слева">
+      <div style={{ display: "inline-block", position: "absolute", right: 0 }}>
+        <Avatar />
+      </div>
+    </Tooltip>
+    <Tooltip text="Я прилип справа">
+      <div style={{ display: "inline-block" }}>
+        <Avatar />
+      </div>
+    </Tooltip>
+    <Tooltip text="Я прилип слева">
+      <div
+        style={{
+          display: "inline-block",
+          position: "absolute",
+          left: 0,
+          bottom: 0,
+        }}
+      >
+        <Avatar />
+      </div>
+    </Tooltip>
+    <Tooltip text="Я прилип справа">
+      <div
+        style={{
+          display: "inline-block",
+          position: "absolute",
+          right: 0,
+          bottom: 0,
+        }}
+      >
+        <Avatar />
+      </div>
+    </Tooltip>
+    <Tooltip text="Я по центру 😎">
+      <div
+        style={{
+          display: "inline-block",
+          position: "absolute",
+          left: "50%",
+          top: "50%",
+          transform: "translate(50%, 50%)",
+        }}
+      >
+        <Avatar />
+      </div>
+    </Tooltip>
+  </TooltipContainer>
+  <div style={{ height: "100vh" }}></div>
+  <TooltipContainer
+    fixed
+    style={{ position: "fixed", bottom: 0, width: "100%" }}
+  >
+    <Tooltip text="Я прибит к низу">
+      <div style={{ display: "inline-block" }}>
+        <Avatar />
+      </div>
+    </Tooltip>
+  </TooltipContainer>
+</>
+```

package/src/components/Tooltip/Tooltip.css

@@ -0,0 +1,73 @@
+.Tooltip {
+  position: absolute;
+  left: 0;
+  top: 0;
+  height: 100%;
+  width: 100%;
+  z-index: 2;
+  white-space: normal;
+}
+
+.Tooltip__container {
+  position: absolute;
+}
+
+.Tooltip__container[data-popper-placement^="bottom"] .Tooltip__corner {
+  top: -8px;
+}
+
+.Tooltip__container[data-popper-placement^="top"] .Tooltip__corner {
+  bottom: -8px;
+}
+
+.Tooltip__container[data-popper-placement^="top"] .Tooltip__corner::before {
+  transform: rotate(180deg);
+}
+
+.Tooltip__container[data-popper-placement^="left"] .Tooltip__corner {
+  right: -14px;
+}
+
+.Tooltip__container[data-popper-placement^="left"] .Tooltip__corner::before {
+  transform: rotate(90deg);
+}
+
+.Tooltip__container[data-popper-placement^="right"] .Tooltip__corner {
+  left: -14px;
+}
+
+.Tooltip__container[data-popper-placement^="right"] .Tooltip__corner::before {
+  transform: rotate(-90deg);
+}
+
+.Tooltip__corner {
+  width: 20px;
+  height: 8px;
+  position: absolute;
+}
+
+.Tooltip__corner::before {
+  content: "";
+  display: block;
+  background-image: url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHdpZHRoPSIyMHB4IiBoZWlnaHQ9IjhweCIgdmlld0JveD0iMCAwIDIwIDgiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+ICAgICAgICA8dGl0bGU+dG9vbHRpcF90aXA8L3RpdGxlPiAgICA8ZGVzYz5DcmVhdGVkIHdpdGggU2tldGNoLjwvZGVzYz4gICAgPGRlZnM+PC9kZWZzPiAgICA8ZyBpZD0iTWFzdGVyLUtpdCIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+ICAgICAgICA8cGF0aCBkPSJNMTAsMCBDMTMuNSwwIDE1LjUsOCAyMCw4IEwwLDggQzQuNSw4IDYuNSwwIDEwLDAgWiIgaWQ9InRvb2x0aXBfdGlwIiBmaWxsPSIjNDdhM2ZmIiBmaWxsLXJ1bGU9Im5vbnplcm8iPjwvcGF0aD4gICAgPC9nPjwvc3ZnPg==);
+  width: 20px;
+  height: 8px;
+}
+
+.Tooltip--light .Tooltip__corner::before {
+  background-image: url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHdpZHRoPSIyMHB4IiBoZWlnaHQ9IjhweCIgdmlld0JveD0iMCAwIDIwIDgiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+ICAgICAgICA8dGl0bGU+dG9vbHRpcF90aXA8L3RpdGxlPiAgICA8ZGVzYz5DcmVhdGVkIHdpdGggU2tldGNoLjwvZGVzYz4gICAgPGRlZnM+PC9kZWZzPiAgICA8ZyBpZD0iTWFzdGVyLUtpdCIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+ICAgICAgICA8cGF0aCBkPSJNMTAsMCBDMTMuNSwwIDE1LjUsOCAyMCw4IEwwLDggQzQuNSw4IDYuNSwwIDEwLDAgWiIgaWQ9InRvb2x0aXBfdGlwIiBmaWxsPSIjZmZmIiBmaWxsLXJ1bGU9Im5vbnplcm8iPjwvcGF0aD4gICAgPC9nPjwvc3ZnPg==);
+}
+
+.Tooltip__content {
+  background-color: #47a3ff;
+  box-shadow: 0 4px 32px 0 rgba(0, 0, 0, 0.16), 0 0 4px 0 rgba(0, 0, 0, 0.04);
+  padding: 8px 12px 10px;
+  border-radius: 10px;
+  color: #fff;
+  max-width: 220px;
+}
+
+.Tooltip--light .Tooltip__content {
+  background: #fff;
+  color: #2c2d2e;
+}

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,314 @@
+import * as React from "react";
+import ReactDOM from "react-dom";
+import { classNames } from "../../lib/classNames";
+import { getClassName } from "../../helpers/getClassName";
+import Subhead from "../Typography/Subhead/Subhead";
+import { useNavTransition } from "../NavTransitionContext/NavTransitionContext";
+import { Modifier, usePopper } from "react-popper";
+import { Placement } from "@popperjs/core";
+import { tooltipContainerAttr } from "./TooltipContainer";
+import { useExternRef } from "../../hooks/useExternRef";
+import { useDOM } from "../../lib/dom";
+import { warnOnce } from "../../lib/warnOnce";
+import { hasReactNode } from "../../lib/utils";
+import { useGlobalEventListener } from "../../hooks/useGlobalEventListener";
+import "./Tooltip.css";
+
+interface SimpleTooltipProps extends Partial<TooltipProps> {
+  target?: HTMLDivElement;
+  arrowRef?: React.Ref<HTMLDivElement>;
+  style?: {
+    arrow: React.CSSProperties;
+    container: React.CSSProperties;
+  };
+  attributes?: {
+    arrow: React.HTMLAttributes<HTMLDivElement> | null;
+    container: React.HTMLAttributes<HTMLDivElement> | null;
+  };
+}
+
+const isDOMTypeElement = (
+  element: React.ReactElement
+): element is React.DOMElement<any, any> => {
+  return React.isValidElement(element) && typeof element.type === "string";
+};
+
+const baseClassName = getClassName("Tooltip");
+const warn = warnOnce("Tooltip");
+const IS_DEV = process.env.NODE_ENV === "development";
+
+const SimpleTooltip = React.forwardRef<HTMLDivElement, SimpleTooltipProps>(
+  function SimpleTooltip(
+    { mode = "accent", header, text, arrowRef, style = {}, attributes },
+    ref
+  ) {
+    return (
+      <div vkuiClass={classNames(baseClassName, `Tooltip--${mode}`)}>
+        <div
+          vkuiClass="Tooltip__container"
+          ref={ref}
+          style={style.container}
+          {...attributes?.container}
+        >
+          <div
+            vkuiClass="Tooltip__corner"
+            style={style.arrow}
+            {...attributes?.arrow}
+            ref={arrowRef}
+          />
+          <div vkuiClass="Tooltip__content">
+            {header && (
+              <Subhead weight="1" vkuiClass="Tooltip__title">
+                {header}
+              </Subhead>
+            )}
+            {text && <Subhead vkuiClass="Tooltip__text">{text}</Subhead>}
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+export interface TooltipProps {
+  /**
+   * **Важно**: если в `children` передан React-компонент, то необходимо убедиться в том, что он поддерживает
+   * свойство `getRootRef`, которое должно возвращаться ссылку на корневой DOM-элемент компонента,
+   * иначе тултип показан не будет. Если передан React-element, то такой проблемы нет.
+   */
+  children: React.ReactElement;
+  mode?: "accent" | "light";
+  /**
+   * Если передан `false`, то рисуется просто `children`.
+   */
+  isShown?: boolean;
+  /**
+   * Текст тултипа.
+   */
+  text?: React.ReactNode;
+  /**
+   * Заголовок тултипа.
+   */
+  header?: React.ReactNode;
+  /**
+   * Положение по горизонтали (прижатие к левому или правому краю `children`).
+   * Если не задано, позиция по горизонтали определятся автоматически
+   */
+  alignX?: "center" | "left" | "right";
+  /**
+   * Положение по вертикали (расположение над или под `children`).
+   * Если не задано, позиция по вертикали определятся автоматически
+   */
+  alignY?: "top" | "bottom";
+  /**
+   * Сдвиг по горизонтали (относительно портала, в котором рисуется тултип).
+   */
+  offsetX?: number;
+  /**
+   * Сдвиг по вертикали (относительно портала, в котором рисуется тултип).
+   */
+  offsetY?: number;
+  /**
+   * Сдвиг стрелочки относительно центра дочернего элемента.
+   */
+  cornerOffset?: number;
+  /**
+   * Сдвиг стрелочки относительно ширины тултипа
+   */
+  cornerAbsoluteOffset?: number;
+  /**
+   * Callback, который вызывается при клике по любому месту в пределах экрана.
+   */
+  onClose?: () => void;
+}
+
+declare type ArrowOffsetModifierOptions = {
+  offset: number;
+};
+declare type ArrowOffsetModifier = Modifier<
+  "arrowOffset",
+  ArrowOffsetModifierOptions
+>;
+
+function mapAlignX(x: TooltipProps["alignX"]) {
+  switch (x) {
+    case "left":
+      return "start";
+    case "right":
+      return "end";
+    default:
+      return "";
+  }
+}
+function getPlacement(
+  alignX: TooltipProps["alignX"],
+  alignY: TooltipProps["alignY"]
+): Placement {
+  return [alignY || "bottom", mapAlignX(alignX || "left")]
+    .filter((p) => !!p)
+    .join("-") as Placement;
+}
+function isVerticalPlacement(placement: Placement) {
+  return placement.startsWith("top") || placement.startsWith("bottom");
+}
+
+const Tooltip: React.FC<TooltipProps> = ({
+  children,
+  isShown: _isShown,
+  offsetX = 0,
+  offsetY = 15,
+  alignX,
+  alignY,
+  onClose,
+  cornerOffset = 0,
+  cornerAbsoluteOffset,
+  ...restProps
+}) => {
+  const { entering } = useNavTransition();
+  const isShown = _isShown && !entering;
+  const [tooltipRef, setTooltipRef] = React.useState<HTMLElement | null>(null);
+  const [tooltipArrowRef, setTooltipArrowRef] =
+    React.useState<HTMLElement | null>(null);
+  const [target, setTarget] = React.useState<HTMLElement>();
+
+  if (IS_DEV) {
+    const multiChildren = React.Children.count(children) > 1;
+    // Empty children is a noop
+    const primitiveChild =
+      hasReactNode(children) && typeof children !== "object";
+    (multiChildren || primitiveChild) &&
+      warn(
+        [
+          "children must be a single React element, got",
+          multiChildren && "multiple",
+          primitiveChild && JSON.stringify(children),
+        ]
+          .filter(Boolean)
+          .join(" ")
+      );
+  }
+
+  /* eslint-disable no-restricted-properties */
+  /* eslint-disable @typescript-eslint/no-unnecessary-type-assertion*/
+  const tooltipContainer = React.useMemo(
+    () => target?.closest(`[${tooltipContainerAttr}]`) as HTMLDivElement,
+    [target]
+  );
+  const strategy = React.useMemo(
+    () => (target?.style.position === "fixed" ? "fixed" : "absolute"),
+    [target]
+  );
+  /* eslint-enable @typescript-eslint/no-unnecessary-type-assertion*/
+  /* eslint-enable no-restricted-properties */
+
+  if (IS_DEV && target && !tooltipContainer) {
+    throw new Error(
+      "Use TooltipContainer for Tooltip outside Panel (see docs)"
+    );
+  }
+
+  const arrowOffsetModiifer = React.useMemo<ArrowOffsetModifier>(() => {
+    return {
+      name: "arrowOffset",
+      enabled: true,
+      phase: "main",
+      fn({ state }) {
+        if (!state.modifiersData.arrow) {
+          return;
+        }
+        if (isVerticalPlacement(state.placement)) {
+          if (cornerAbsoluteOffset !== undefined) {
+            state.modifiersData.arrow.x = cornerAbsoluteOffset;
+          } else {
+            if (state.modifiersData.arrow?.x !== undefined) {
+              state.modifiersData.arrow.x += cornerOffset;
+            }
+          }
+        } else {
+          if (cornerAbsoluteOffset !== undefined) {
+            state.modifiersData.arrow.y = cornerAbsoluteOffset;
+          } else {
+            if (state.modifiersData.arrow?.y !== undefined) {
+              state.modifiersData.arrow.y += cornerOffset;
+            }
+          }
+        }
+      },
+    };
+  }, [cornerOffset, cornerAbsoluteOffset]);
+
+  const placement = getPlacement(alignX, alignY);
+  const { styles, attributes } = usePopper(target, tooltipRef, {
+    strategy,
+    placement,
+    modifiers: [
+      {
+        name: "offset",
+        options: {
+          offset: [offsetX, offsetY],
+        },
+      },
+      {
+        name: "arrow",
+        options: {
+          element: tooltipArrowRef,
+          padding: 14,
+        },
+      },
+      {
+        name: "preventOverflow",
+      },
+      {
+        name: "flip",
+      },
+      arrowOffsetModiifer,
+    ],
+  });
+
+  const { document } = useDOM();
+  useGlobalEventListener(document, "click", isShown && onClose, {
+    passive: true,
+  });
+  // NOTE: setting isShown to true used to trigger usePopper().forceUpdate()
+
+  const childRef =
+    React.isValidElement(children) &&
+    (isDOMTypeElement(children) ? children.ref : children.props.getRootRef);
+  const patchedRef = useExternRef(setTarget, childRef);
+  const child = React.isValidElement(children)
+    ? React.cloneElement(children, {
+        [isDOMTypeElement(children) ? "ref" : "getRootRef"]: patchedRef,
+      })
+    : children;
+
+  return (
+    <React.Fragment>
+      {child}
+      {isShown &&
+        target != null &&
+        ReactDOM.createPortal(
+          <SimpleTooltip
+            {...restProps}
+            ref={(el) => setTooltipRef(el)}
+            arrowRef={(el) => setTooltipArrowRef(el)}
+            style={{ arrow: styles.arrow, container: styles.popper }}
+            attributes={{
+              arrow: attributes.arrow ?? null,
+              container: attributes.popper ?? null,
+            }}
+          />,
+          tooltipContainer
+        )}
+    </React.Fragment>
+  );
+};
+
+Tooltip.defaultProps = {
+  offsetX: 0,
+  offsetY: 15,
+  cornerOffset: 0,
+  isShown: true,
+  mode: "accent",
+};
+// eslint-disable-next-line import/no-default-export
+export default Tooltip;

package/src/components/Tooltip/TooltipContainer.tsx

@@ -0,0 +1,10 @@
+import * as React from "react";
+
+export const tooltipContainerAttr = "data-tooltip-container";
+export const TooltipContainer = React.forwardRef<
+  HTMLDivElement,
+  React.HtmlHTMLAttributes<HTMLDivElement> & { fixed?: boolean }
+>(function TooltipContainer({ fixed = false, ...props }, ref) {
+  (props as any)[tooltipContainerAttr] = fixed ? "fixed" : "true";
+  return <div {...props} ref={ref} />;
+});