@vkontakte/vkui 4.34.0 → 4.35.0

package/src/components/CustomSelectDropdown/CustomSelectDropdown.tsx

@@ -6,6 +6,7 @@ import { classNames } from "../../lib/classNames";
 import { Popper, Placement } from "../Popper/Popper";
 import { Spinner } from "../Spinner/Spinner";
 import { HasRef } from "../../types";
+import { useIsomorphicLayoutEffect } from "../../lib/useIsomorphicLayoutEffect";
 import "./CustomSelectDropdown.css";
 
 export interface CustomSelectDropdownProps
@@ -15,6 +16,9 @@ export interface CustomSelectDropdownProps
   targetRef: React.RefObject<HTMLElement>;
   placement?: Placement;
   scrollBoxRef?: React.RefObject<HTMLDivElement>;
+  observableRefs?:
+    | Array<React.RefObject<HTMLElement>>
+    | React.RefObject<HTMLElement>;
   fetching?: boolean;
   offsetDistance?: number;
   sameWidth?: boolean;
@@ -24,6 +28,28 @@ export interface CustomSelectDropdownProps
 
 const calcIsTop = (placement?: Placement) => placement?.includes("top");
 
+function getObserverModifier<T extends HTMLElement>(
+  element: T
+): Modifier<string> {
+  return {
+    name: "customSelectChildrenChange",
+    enabled: true,
+    phase: "main",
+    effect: ({ instance }) => {
+      const observer = new MutationObserver(instance.forceUpdate);
+
+      observer.observe(element, {
+        childList: true,
+        subtree: true,
+      });
+
+      return () => {
+        observer.disconnect();
+      };
+    },
+  };
+}
+
 export const CustomSelectDropdown = ({
   children,
   targetRef,
@@ -36,35 +62,32 @@ export const CustomSelectDropdown = ({
   forcePortal = true,
   autoHideScrollbar,
   autoHideScrollbarDelay,
+  observableRefs,
   ...restProps
 }: CustomSelectDropdownProps) => {
   const [isTop, setIsTop] = React.useState(() => calcIsTop(placement));
+  const [customModifiers, setCustomModifiers] = React.useState<
+    Array<Modifier<string>>
+  >([]);
 
-  const customModifiers = React.useMemo<Array<Modifier<string>>>(() => {
-    if (!scrollBoxRef?.current) {
-      return [];
+  useIsomorphicLayoutEffect(() => {
+    if (!observableRefs) {
+      return;
     }
+    const customModifiers: Array<Modifier<string>> = [];
 
-    return [
-      {
-        name: "customSelectChildrenChange",
-        enabled: true,
-        phase: "main",
-        effect: ({ instance }) => {
-          const observer = new MutationObserver(instance.forceUpdate);
-
-          observer.observe(scrollBoxRef.current as Element, {
-            childList: true,
-          });
+    if (Array.isArray(observableRefs)) {
+      for (const ref of observableRefs) {
+        if (ref?.current) {
+          customModifiers.push(getObserverModifier(ref.current));
+        }
+      }
+    } else if (observableRefs.current) {
+      customModifiers.push(getObserverModifier(observableRefs.current));
+    }
 
-          return () => {
-            observer.disconnect();
-          };
-        },
-      },
-    ];
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [scrollBoxRef?.current]);
+    setCustomModifiers(customModifiers);
+  }, [observableRefs]);
 
   const onPlacementChange = React.useCallback(
     ({ placement }: { placement?: Placement }) => {

package/src/components/Dropdown/Dropdown.css

@@ -1,6 +1,18 @@
 .Dropdown {
+  position: relative;
   animation: vkui-popper-fadein 0.2s ease;
   background: var(--modal_card_background, var(--vkui--color_background_modal));
   border-radius: var(--vkui--size_border_radius--regular);
   box-shadow: var(--vkui--elevation3);
 }
+
+/* Создаём "Safe Zone" */
+.Dropdown::before {
+  content: "";
+  position: absolute;
+  z-index: -1;
+  top: calc(-1 * var(--popover-safe-zone-padding));
+  right: calc(-1 * var(--popover-safe-zone-padding));
+  bottom: calc(-1 * var(--popover-safe-zone-padding));
+  left: calc(-1 * var(--popover-safe-zone-padding));
+}

package/src/components/Dropdown/Dropdown.tsx

@@ -1,36 +1,190 @@
-import { HoverPopper, HoverPopperProps } from "../HoverPopper/HoverPopper";
-import { ClickPopper, ClickPopperProps } from "../ClickPopper/ClickPopper";
+import * as React from "react";
+import { useDOM } from "../../lib/dom";
+import { PopperCommonProps, Popper } from "../Popper/Popper";
+import { FocusTrap } from "../FocusTrap/FocusTrap";
+import { useTimeout } from "../../hooks/useTimeout";
+import { useExternRef } from "../../hooks/useExternRef";
+import { useEventListener } from "../../hooks/useEventListener";
+import { useGlobalEventListener } from "../../hooks/useGlobalEventListener";
+import { usePatchChildrenRef } from "../../hooks/usePatchChildrenRef";
 import "./Dropdown.css";
 
 export interface DropdownProps
-  extends Omit<ClickPopperProps, "arrow" | "arrowClassName">,
-    Omit<HoverPopperProps, "arrow" | "arrowClassName"> {
+  extends Omit<PopperCommonProps, "arrow" | "arrowClassName"> {
+  /**
+   * Механика вызова всплывающего окна.
+   *
+   * - `"click"` – показывается/скрывается только при нажатии.
+   * - `"hover"` – помимо нажатия, будет показываться/скрывается при наведении/отведении мыши.
+   *
+   * > ⚠️`"hover"` на тач-устройствах будет работать как `"click"`, с одним лишь нюансом, что не будет закрываться
+   * > при повторном нажатии на целевой элемент. Для закрытия необходимо нажать на область вне целевого элемента
+   * > и выпадающего окна.
+   */
   action?: "click" | "hover";
+  /**
+   * Если передан, то всплывающее окно будет показан/скрыт в зависимости от значения свойства.
+   */
+  shown?: boolean;
+  /**
+   * Количество миллисекунд, после которых произойдёт показ всплывающего окна.
+   *
+   * > Используется только для `action="hover"` при наведении/отведении мыши.
+   */
+  showDelay?: number;
+  /**
+   * Количество миллисекунд, после которых произойдёт скрытие всплывающего окна.
+   *
+   * > Используется только для `action="hover"` при наведении/отведении мыши.
+   */
+  hideDelay?: number;
+  /**
+   * Содержимое всплывающего окна.
+   */
+  content?: React.ReactNode;
+  /**
+   * Целевой элемент. Всплывающее окно появится возле него.
+   *
+   * > ⚠️ Если это пользовательский компонент, то он должен предоставлять параметры либо `getRootRef`, либо `ref` для получения ссылки на DOM-узел.
+   */
+  children?: React.ReactElement;
+  /**
+   * Вызывается при каждом изменении видимости всплывающего окна.
+   */
+  onShownChange?(shown: boolean): void;
 }
 
 /**
  * @see https://vkcom.github.io/VKUI/#/Dropdown
+ *
+ * TODO v5.0.0 Переименовать в `Popover` (см. https://github.com/VKCOM/VKUI/issues/2523)
  */
 export const Dropdown = ({
   action = "click",
-  hideDelay,
-  showDelay,
-  ...popperProps
+  shown: shownProp,
+  showDelay = 150,
+  hideDelay = 150,
+  offsetDistance = 8,
+  content,
+  children,
+  style,
+  getRef,
+  onShownChange,
+  ...restProps
 }: DropdownProps) => {
-  let Component;
-  let actionSpecificProps: Partial<DropdownProps> = {};
-
-  switch (action) {
-    case "click":
-      Component = ClickPopper;
-      break;
-    case "hover":
-      actionSpecificProps = { hideDelay, showDelay };
-      Component = HoverPopper;
-      break;
-  }
+  const { document } = useDOM();
+
+  const hoverable = action === "hover";
+  const hovered = React.useRef(false);
+  const [computedShown, setComputedShown] = React.useState(shownProp || false);
+  const [dropdownNode, setPopperNode] = React.useState<HTMLElement | null>(
+    null
+  );
+
+  // Reason: Typescript ругается на CSS Custom Properties в объекте
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const styles = {
+    ...style,
+    "--popover-safe-zone-padding": `${offsetDistance}px`,
+  } as React.CSSProperties;
+
+  const shown = typeof shownProp === "boolean" ? shownProp : computedShown;
+
+  const patchedPopperRef = useExternRef<HTMLDivElement>(setPopperNode, getRef);
+
+  const [childRef, child] = usePatchChildrenRef(children);
+
+  const setShown = (value: boolean) => {
+    if (typeof shownProp !== "boolean") {
+      setComputedShown(value);
+    }
+    typeof onShownChange === "function" && onShownChange(value);
+  };
+
+  const showTimeout = useTimeout(() => setShown(true), showDelay);
+
+  const hideTimeout = useTimeout(() => setShown(false), hideDelay);
+
+  const handleTargetEnter = () => {
+    hovered.current = true;
+    hideTimeout.clear();
+    showTimeout.set();
+  };
+
+  const handleTargetClick = () => {
+    if (hovered.current && shown) {
+      return;
+    }
+    setShown(!shown);
+  };
+
+  const handleTargetLeave = () => {
+    hovered.current = false;
+    showTimeout.clear();
+    hideTimeout.set();
+  };
+
+  const handleContentKeyDownEscape = () => {
+    setShown(false);
+  };
+
+  const handleOutsideClick = (e: MouseEvent) => {
+    if (
+      dropdownNode &&
+      !childRef.current?.contains(e.target as Node) &&
+      !dropdownNode.contains(e.target as Node)
+    ) {
+      setShown(false);
+    }
+  };
+
+  useGlobalEventListener(document, "click", handleOutsideClick);
+  const targetEnterListener = useEventListener("mouseenter", handleTargetEnter);
+  const targetClickEvent = useEventListener("click", handleTargetClick);
+  const targetLeaveListener = useEventListener("mouseleave", handleTargetLeave);
+
+  React.useEffect(() => {
+    if (!childRef.current) {
+      return;
+    }
+
+    targetClickEvent.add(childRef.current);
+
+    if (hoverable) {
+      targetEnterListener.add(childRef.current);
+      targetLeaveListener.add(childRef.current);
+    }
+  }, [
+    childRef,
+    hoverable,
+    targetClickEvent,
+    targetEnterListener,
+    targetLeaveListener,
+  ]);
 
   return (
-    <Component vkuiClass="Dropdown" {...actionSpecificProps} {...popperProps} />
+    <React.Fragment>
+      {child}
+      {shown && (
+        <Popper
+          {...restProps}
+          vkuiClass="Dropdown"
+          targetRef={childRef}
+          getRef={patchedPopperRef}
+          offsetDistance={offsetDistance}
+          style={styles}
+          renderContent={({ className }) => (
+            <FocusTrap
+              vkuiClass={className}
+              onClose={handleContentKeyDownEscape}
+            >
+              {content}
+            </FocusTrap>
+          )}
+          onMouseOver={hoverable ? hideTimeout.clear : undefined}
+          onMouseOut={hoverable ? handleTargetLeave : undefined}
+        />
+      )}
+    </React.Fragment>
   );
 };

package/src/components/Dropdown/Readme.md

@@ -23,6 +23,7 @@ return (
     </Dropdown>
 
     <Dropdown
+      action="click"
       shown={shown}
       onShownChange={setShown}
       content={

package/src/components/Epic/Epic.tsx

@@ -1,6 +1,4 @@
 import * as React from "react";
-import { getClassName } from "../../helpers/getClassName";
-import { usePlatform } from "../../hooks/usePlatform";
 import { withAdaptivity, ViewWidth } from "../../hoc/withAdaptivity";
 import { ScrollSaver } from "./ScrollSaver";
 import { getNavId } from "../../lib/getNavId";
@@ -28,7 +26,6 @@ const EpicComponent = ({
   viewWidth,
   ...restProps
 }: EpicProps & AdaptivityContextInterface) => {
-  const platform = usePlatform();
   const scroll = React.useRef<{ [key: string]: number }>({}).current;
 
   if (
@@ -48,7 +45,7 @@ const EpicComponent = ({
     ) as React.ReactElement | undefined) ?? null;
 
   return (
-    <div {...restProps} vkuiClass={getClassName("Epic", platform)}>
+    <div {...restProps} vkuiClass="Epic">
       <ScrollSaver
         key={activeStory}
         initialScroll={scroll[activeStory] || 0}

package/src/components/FixedLayout/Readme.md

@@ -1,117 +1,111 @@
-`{ position: fixed }` не дружит с `{ transform: translate }` на родителе, поэтому для позиционирования фиксированных
-блоков внутри панели, необходимо использовать `FixedLayout` в качестве обертки.
+Компонент закрепляет переданный элемент сверху или снизу области видимости. Учитывает высоту шапки и прочие системные отступы.
 
-Для удобства есть свойство `vertical`, с помощью которого можно "прижать" контент к верху или низу.
-При этому будут учитываться высота шапки и прочие системные отступы.
-
-**Важно:** блок с `{ position: fixed }` находится не в потоке. В примере можно увидеть, что у блока с основным
-контентом есть паддинги. Они там не случайны.
+> ⚠️ Использует `position: fixed` вместо `position: sticky`, т.к. библиотека поддерживает версии браузеров,
+> где значение `sticky` отсутствует. По этой причине `FixedLayout` находится вне основного потока. В примере ниже можно
+> увидеть, что у блока с основным контентом есть отступы сверху и снизу (см. `contentStyles`). Без них контент
+> залезал бы под `FixedLayout`.
 
 ```jsx
-class Example extends React.Component {
-  constructor(props) {
-    super(props);
+const contentStyles = {
+  paddingTop: 60,
+  paddingBottom: 60,
+};
 
-    this.state = {
-      activeTab: "groups",
-    };
-  }
+const Example = () => {
+  const [activeTab, setActiveTab] = React.useState("groups");
 
-  render() {
-    return (
-      <View activePanel="fixedLayout">
-        <Panel id="fixedLayout">
-          <PanelHeader>Fixed layout</PanelHeader>
-          <Group>
-            <FixedLayout vertical="top">
-              <Search />
-            </FixedLayout>
-            <Div style={{ paddingTop: 60, paddingBottom: 60, color: "gray" }}>
-              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed a
-              sollicitudin lectus, a commodo sapien. Vivamus a urna leo. Integer
-              iaculis dignissim urna, sit amet vestibulum diam bibendum a. Donec
-              eu arcu ut augue porttitor faucibus. Vestibulum nec pretium
-              tortor, sit amet congue nunc. Aenean ullamcorper ex sem, sed
-              interdum quam consequat et. Vestibulum a ex non diam fringilla
-              feugiat. Nunc eu tellus sed leo elementum cursus. Mauris blandit
-              porta egestas. Curabitur eget justo elementum, malesuada lacus ut,
-              congue mauris. Integer orci nisi, convallis vitae dapibus sit
-              amet, molestie a risus. Aenean ultricies lacus eros, sit amet
-              condimentum urna malesuada et. Sed quis dolor tempus orci
-              fringilla volutpat in sed velit. Aenean aliquet bibendum pretium.
-              <br />
-              <br />
-              Cras pulvinar lobortis purus. Donec placerat suscipit leo vitae sodales.
-              Phasellus convallis lorem vitae arcu finibus pellentesque. In imperdiet
-              vel leo a euismod. Nam sed odio a neque venenatis suscipit a placerat
-              magna. Mauris magna nisl, consequat nec augue vitae, ultricies scelerisque
-              ante. Phasellus pharetra risus eget imperdiet sodales. Integer dignissim
-              auctor semper. Nulla odio odio, euismod ut interdum in, bibendum sed
-              massa. Proin rutrum molestie massa in ultrices. Donec eu euismod turpis,
-              eget lobortis lorem. Nulla facilisi. Nam lacinia posuere turpis, sed
-              laoreet turpis auctor nec.
-              <br />
-              <br />
-              Curabitur eu fermentum mauris. Phasellus malesuada consectetur
-              mollis. Pellentesque pulvinar mauris turpis. Integer neque dolor,
-              semper quis neque et, gravida commodo eros. Duis efficitur ex a
-              turpis blandit tincidunt. Mauris sem mi, imperdiet quis ligula sit
-              amet, fermentum vulputate felis. Phasellus eu ullamcorper dolor,
-              porttitor pulvinar diam. Aliquam euismod, mauris nec varius
-              lacinia, ligula libero vulputate leo, ut tristique massa nisi
-              vitae tortor. Phasellus purus elit, gravida sit amet neque id,
-              aliquam rutrum dui. Maecenas luctus sem vitae molestie porttitor.
-              Cras viverra mauris risus, at sollicitudin ipsum interdum eu. Sed
-              sit amet tempor enim.
-              <br />
-              <br />
-              In hac habitasse platea dictumst. Etiam luctus erat metus, quis efficitur
-              quam vulputate quis. Duis ultricies non mauris condimentum molestie.
-              Maecenas sollicitudin ex sem, quis ultrices libero blandit eu. Vivamus
-              in turpis pulvinar, malesuada enim at, hendrerit magna. Proin eu nulla
-              eget arcu pretium pharetra. Sed ullamcorper pulvinar est eu dapibus.
-              Cras at varius justo. In ex odio, condimentum id pellentesque a, sodales
-              ut diam.
-              <br />
-              <br />
-              Vestibulum ante ipsum primis in faucibus orci luctus et ultrices
-              posuere cubilia Curae; Nam aliquet tempor laoreet. Maecenas eu
-              pulvinar diam. Pellentesque habitant morbi tristique senectus et
-              netus et malesuada fames ac turpis egestas. Maecenas et elit eros.
-              Quisque ullamcorper sodales nisi, eleifend aliquet metus venenatis
-              in. Aliquam ornare a lacus in tincidunt. Cras vel tristique metus.
-              Sed vitae nisl at nisl imperdiet sollicitudin. Sed sit amet enim
-              in lectus imperdiet interdum condimentum et diam. Proin venenatis
-              sit amet diam ac vulputate. Donec mauris orci, semper volutpat
-              nunc ut, efficitur condimentum dolor. Vivamus in quam eget quam
-              lacinia pharetra. Phasellus ipsum magna, aliquet id elit eget,
-              cursus tincidunt ex. In rhoncus turpis turpis, et viverra ex
-              malesuada vel. Donec nisi tellus, mollis et posuere vel, dictum
-              eget neque.
-            </Div>
-            <FixedLayout filled vertical="bottom">
-              <Separator wide />
-              <Tabs>
-                <TabsItem
-                  selected={this.state.activeTab === "groups"}
-                  onClick={() => this.setState({ activeTab: "groups" })}
-                >
-                  176 сообществ
-                </TabsItem>
-                <TabsItem
-                  selected={this.state.activeTab === "events"}
-                  onClick={() => this.setState({ activeTab: "events" })}
-                >
-                  9 событий
-                </TabsItem>
-              </Tabs>
-            </FixedLayout>
-          </Group>
-        </Panel>
-      </View>
-    );
-  }
-}
+  return (
+    <View activePanel="fixedLayout">
+      <Panel id="fixedLayout">
+        <PanelHeader>Fixed layout</PanelHeader>
+        <FixedLayout vertical="top">
+          <Search />
+          <Separator wide />
+        </FixedLayout>
+        <Group>
+          <Div style={contentStyles}>
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed a
+            sollicitudin lectus, a commodo sapien. Vivamus a urna leo. Integer
+            iaculis dignissim urna, sit amet vestibulum diam bibendum a. Donec
+            eu arcu ut augue porttitor faucibus. Vestibulum nec pretium tortor,
+            sit amet congue nunc. Aenean ullamcorper ex sem, sed interdum quam
+            consequat et. Vestibulum a ex non diam fringilla feugiat. Nunc eu
+            tellus sed leo elementum cursus. Mauris blandit porta egestas.
+            Curabitur eget justo elementum, malesuada lacus ut, congue mauris.
+            Integer orci nisi, convallis vitae dapibus sit amet, molestie a
+            risus. Aenean ultricies lacus eros, sit amet condimentum urna
+            malesuada et. Sed quis dolor tempus orci fringilla volutpat in sed
+            velit. Aenean aliquet bibendum pretium.
+            <br />
+            <br />
+            Cras pulvinar lobortis purus. Donec placerat suscipit leo vitae sodales.
+            Phasellus convallis lorem vitae arcu finibus pellentesque. In imperdiet
+            vel leo a euismod. Nam sed odio a neque venenatis suscipit a placerat
+            magna. Mauris magna nisl, consequat nec augue vitae, ultricies scelerisque
+            ante. Phasellus pharetra risus eget imperdiet sodales. Integer dignissim
+            auctor semper. Nulla odio odio, euismod ut interdum in, bibendum sed
+            massa. Proin rutrum molestie massa in ultrices. Donec eu euismod turpis,
+            eget lobortis lorem. Nulla facilisi. Nam lacinia posuere turpis, sed
+            laoreet turpis auctor nec.
+            <br />
+            <br />
+            Curabitur eu fermentum mauris. Phasellus malesuada consectetur
+            mollis. Pellentesque pulvinar mauris turpis. Integer neque dolor,
+            semper quis neque et, gravida commodo eros. Duis efficitur ex a
+            turpis blandit tincidunt. Mauris sem mi, imperdiet quis ligula sit
+            amet, fermentum vulputate felis. Phasellus eu ullamcorper dolor,
+            porttitor pulvinar diam. Aliquam euismod, mauris nec varius lacinia,
+            ligula libero vulputate leo, ut tristique massa nisi vitae tortor.
+            Phasellus purus elit, gravida sit amet neque id, aliquam rutrum dui.
+            Maecenas luctus sem vitae molestie porttitor. Cras viverra mauris
+            risus, at sollicitudin ipsum interdum eu. Sed sit amet tempor enim.
+            <br />
+            <br />
+            In hac habitasse platea dictumst. Etiam luctus erat metus, quis efficitur
+            quam vulputate quis. Duis ultricies non mauris condimentum molestie.
+            Maecenas sollicitudin ex sem, quis ultrices libero blandit eu. Vivamus
+            in turpis pulvinar, malesuada enim at, hendrerit magna. Proin eu nulla
+            eget arcu pretium pharetra. Sed ullamcorper pulvinar est eu dapibus.
+            Cras at varius justo. In ex odio, condimentum id pellentesque a, sodales
+            ut diam.
+            <br />
+            <br />
+            Vestibulum ante ipsum primis in faucibus orci luctus et ultrices
+            posuere cubilia Curae; Nam aliquet tempor laoreet. Maecenas eu
+            pulvinar diam. Pellentesque habitant morbi tristique senectus et
+            netus et malesuada fames ac turpis egestas. Maecenas et elit eros.
+            Quisque ullamcorper sodales nisi, eleifend aliquet metus venenatis
+            in. Aliquam ornare a lacus in tincidunt. Cras vel tristique metus.
+            Sed vitae nisl at nisl imperdiet sollicitudin. Sed sit amet enim in
+            lectus imperdiet interdum condimentum et diam. Proin venenatis sit
+            amet diam ac vulputate. Donec mauris orci, semper volutpat nunc ut,
+            efficitur condimentum dolor. Vivamus in quam eget quam lacinia
+            pharetra. Phasellus ipsum magna, aliquet id elit eget, cursus
+            tincidunt ex. In rhoncus turpis turpis, et viverra ex malesuada vel.
+            Donec nisi tellus, mollis et posuere vel, dictum eget neque.
+          </Div>
+        </Group>
+        <FixedLayout filled vertical="bottom">
+          <Separator wide />
+          <Tabs>
+            <TabsItem
+              selected={activeTab === "groups"}
+              onClick={() => setActiveTab("groups")}
+            >
+              176 сообществ
+            </TabsItem>
+            <TabsItem
+              selected={activeTab === "events"}
+              onClick={() => setActiveTab("events")}
+            >
+              9 событий
+            </TabsItem>
+          </Tabs>
+        </FixedLayout>
+      </Panel>
+    </View>
+  );
+};
 
 <Example />;
 ```