@vkontakte/vkui 4.28.0 → 4.29.1

package/src/components/Alert/Readme.md

@@ -0,0 +1,133 @@
+Передаётся в качестве значения свойства `popout` компонента [`SplitLayout`](#/SplitLayout).
+
+В Алертах особое внимание нужно уделить кнопкам. Всего есть три типа кнопок:
+`cancel`, `destructive` и `default`.
+
+Типом `cancel` нужно подсветить действие, возвращающее пользователя к
+состоянию, когда алерт был закрыт. Пользователь кликнет по нему в случае, когда он открыл алерт для
+совершения какого-то действия и передумал.
+
+Стиль `destructive` используется в случае, когда действие влечёт за собой какие-то деструктивные последствия:
+удаление, разжалование и т.д.
+
+Во всех остальных случаях используйте стиль `default`.
+
+Кнопки могут быть ссылками (передайте `href`) или другим компонентом (передайте `Component`).
+
+> **Важно:**
+>
+> 1. Кнопка со стилем `cancel` должна быть одна на алерт.
+> 2. Кнопку со стилем `cancel` нужно располагать либо слева, либо снизу, в зависимости от выбранного `actionsLayout`.
+> 3. В Android версии игнорируется стили `cancel` и `destructive`, и жирность всех кнопок одинаковая.
+> 4. В VKCOM версии возможно только горизонтальное расположение кнопок.
+> 5. Порядок кнопок должен быть одинаковым на всех платформах (см. пункт 2).
+
+```jsx { "props": { "layout": false, "adaptivity": true } }
+class Example extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.state = {
+      popout: null,
+      actionsLog: [],
+    };
+
+    this.openAction = this.openAction.bind(this);
+    this.openDeletion = this.openDeletion.bind(this);
+    this.closePopout = this.closePopout.bind(this);
+    this.addActionLogItem = this.addActionLogItem.bind(this);
+  }
+
+  componentDidMount() {
+    this.openDeletion();
+  }
+
+  addActionLogItem(value) {
+    this.setState({
+      actionsLog: [...this.state.actionsLog, value],
+    });
+  }
+
+  openAction() {
+    this.setState({
+      popout: (
+        <Alert
+          actions={[
+            {
+              title: "Лишить права",
+              mode: "destructive",
+              autoclose: true,
+              action: () =>
+                this.addActionLogItem("Право на модерацию контента убрано."),
+            },
+            {
+              title: "Отмена",
+              autoclose: true,
+              mode: "cancel",
+            },
+          ]}
+          actionsLayout="vertical"
+          onClose={this.closePopout}
+          header="Подтвердите действие"
+          text="Вы уверены, что хотите лишить пользователя права на модерацию контента?"
+        />
+      ),
+    });
+  }
+
+  openDeletion() {
+    this.setState({
+      popout: (
+        <Alert
+          actions={[
+            {
+              title: "Отмена",
+              autoclose: true,
+              mode: "cancel",
+            },
+            {
+              title: "Удалить",
+              autoclose: true,
+              mode: "destructive",
+              action: () => this.addActionLogItem("Документ удален."),
+            },
+          ]}
+          actionsLayout="horizontal"
+          onClose={this.closePopout}
+          header="Удаление документа"
+          text="Вы уверены, что хотите удалить этот документ?"
+        />
+      ),
+    });
+  }
+
+  closePopout() {
+    this.setState({ popout: null });
+  }
+
+  render() {
+    return (
+      <SplitLayout popout={this.state.popout}>
+        <SplitCol>
+          <View activePanel="alert">
+            <Panel id="alert">
+              <PanelHeader>Alert</PanelHeader>
+              <Group>
+                <CellButton onClick={this.openAction}>Лишить права</CellButton>
+                <CellButton onClick={this.openDeletion}>
+                  Удалить документ
+                </CellButton>
+                {this.state.actionsLog.map((value, i) => (
+                  <Div key={i}>{value}</Div>
+                ))}
+              </Group>
+            </Panel>
+          </View>
+        </SplitCol>
+      </SplitLayout>
+    );
+  }
+}
+
+<Example />;
+```

package/src/components/AppRoot/AppRoot.css

@@ -0,0 +1,20 @@
+.vkui__root--embedded {
+  transform: translate3d(0, 0, 0);
+  overflow-x: hidden;
+}
+
+.AppRoot {
+  height: 100%;
+}
+
+.vkui__root--embedded .AppRoot {
+  overflow: auto;
+}
+
+.vkui--sizeX-regular {
+  background: var(--background_page);
+}
+
+.AppRoot--no-mouse {
+  user-select: none;
+}

package/src/components/AppRoot/AppRoot.tsx

@@ -0,0 +1,221 @@
+import * as React from "react";
+import { useDOM } from "../../lib/dom";
+import { classNames } from "../../lib/classNames";
+import { AppRootContext } from "./AppRootContext";
+import {
+  withAdaptivity,
+  SizeType,
+  AdaptivityProps,
+} from "../../hoc/withAdaptivity";
+import { useIsomorphicLayoutEffect } from "../../lib/useIsomorphicLayoutEffect";
+import { classScopingMode } from "../../lib/classScopingMode";
+import { IconSettingsProvider } from "@vkontakte/icons";
+import {
+  elementScrollController,
+  globalScrollController,
+  ScrollContext,
+  ScrollContextInterface,
+} from "./ScrollContext";
+import { noop } from "../../lib/utils";
+import { warnOnce } from "../../lib/warnOnce";
+import { useKeyboardInputTracker } from "../../hooks/useKeyboardInputTracker";
+import { useInsets } from "../../hooks/useInsets";
+import { Insets } from "@vkontakte/vk-bridge";
+import { ConfigProviderContext } from "../ConfigProvider/ConfigProviderContext";
+import "./AppRoot.css";
+
+// Используйте classList, но будьте осторожны
+/* eslint-disable no-restricted-properties */
+
+export interface AppRootProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    Pick<AdaptivityProps, "sizeX" | "hasMouse"> {
+  /** @deprecated Use mode="embedded" */
+  embedded?: boolean;
+  /** Режим встраивания */
+  mode?: "partial" | "embedded" | "full";
+  window?: Window;
+  /** Убирает классы без префикса (.Button) */
+  noLegacyClasses?: boolean;
+  scroll?: "global" | "contain";
+}
+
+const warn = warnOnce("AppRoot");
+export const AppRoot = withAdaptivity<AppRootProps>(
+  ({
+    children,
+    mode: _mode,
+    embedded: _embedded,
+    sizeX,
+    hasMouse,
+    noLegacyClasses = false,
+    scroll = "global",
+    ...props
+  }) => {
+    // normalize mode
+    const mode = _mode || (_embedded ? "embedded" : "full");
+    const isKeyboardInputActive = useKeyboardInputTracker();
+    const rootRef = React.useRef<HTMLDivElement | null>(null);
+    const [portalRoot, setPortalRoot] = React.useState<HTMLDivElement | null>(
+      null
+    );
+    const { window, document } = useDOM();
+    const insets = useInsets();
+    const { appearance } = React.useContext(ConfigProviderContext);
+
+    const initialized = React.useRef(false);
+    if (!initialized.current) {
+      if (document && mode === "full") {
+        document.documentElement.classList.add("vkui");
+      }
+      classScopingMode.noConflict = noLegacyClasses;
+      initialized.current = true;
+    }
+
+    if (process.env.NODE_ENV === "development") {
+      if (scroll !== "global" && mode !== "embedded") {
+        warn(
+          `Свойство scroll="${scroll}" поддерживается только в режиме embedded`,
+          "error"
+        );
+      }
+      if (_mode && _embedded) {
+        warn(`Свойство mode="${mode}" приоритетнее, чем "embedded"`);
+      }
+    }
+
+    // setup portal
+    useIsomorphicLayoutEffect(() => {
+      const portal = document!.createElement("div");
+      portal.classList.add("vkui__portal-root");
+      document!.body.appendChild(portal);
+      setPortalRoot(portal);
+      return () => {
+        portal.parentElement?.removeChild(portal);
+      };
+    }, []);
+
+    // setup root classes
+    useIsomorphicLayoutEffect(() => {
+      if (mode === "partial") {
+        return noop;
+      }
+
+      const parent = rootRef.current?.parentElement;
+      const classes = ["vkui__root"].concat(
+        mode === "embedded" ? "vkui__root--embedded" : []
+      );
+      parent?.classList.add(...classes);
+
+      return () => {
+        parent?.classList.remove(...classes);
+        if (mode === "full") {
+          document?.documentElement.classList.remove("vkui");
+        }
+      };
+    }, []);
+
+    // setup insets
+    useIsomorphicLayoutEffect(() => {
+      if (mode === "partial" || !rootRef.current?.parentElement) {
+        return noop;
+      }
+
+      const parent = rootRef.current.parentElement;
+
+      for (const key in insets) {
+        if (
+          insets.hasOwnProperty(key) &&
+          typeof insets[key as keyof Insets] === "number"
+        ) {
+          const inset = insets[key as keyof Insets];
+          parent.style.setProperty(`--safe-area-inset-${key}`, `${inset}px`);
+          portalRoot &&
+            portalRoot.style.setProperty(
+              `--safe-area-inset-${key}`,
+              `${inset}px`
+            );
+        }
+      }
+
+      return () => {
+        for (const key in insets) {
+          if (insets.hasOwnProperty(key)) {
+            parent.style.removeProperty(`--safe-area-inset-${key}`);
+            portalRoot &&
+              portalRoot.style.removeProperty(`--safe-area-inset-${key}`);
+          }
+        }
+      };
+    }, [insets, portalRoot]);
+
+    // adaptivity handler
+    useIsomorphicLayoutEffect(() => {
+      if (mode === "partial" || sizeX !== SizeType.REGULAR) {
+        return noop;
+      }
+      const container =
+        mode === "embedded" ? rootRef.current?.parentElement : document!.body;
+      container?.classList.add("vkui--sizeX-regular");
+      return () => container?.classList.remove("vkui--sizeX-regular");
+    }, [sizeX]);
+
+    useIsomorphicLayoutEffect(() => {
+      if (mode !== "full" || appearance === undefined) {
+        return noop;
+      }
+      document!.documentElement.style.setProperty("color-scheme", appearance);
+
+      return () =>
+        document!.documentElement.style.removeProperty("color-scheme");
+    }, [appearance]);
+
+    const scrollController = React.useMemo<ScrollContextInterface>(
+      () =>
+        scroll === "contain"
+          ? elementScrollController(rootRef)
+          : globalScrollController(window, document),
+      [document, scroll, window]
+    );
+
+    const content = (
+      <AppRootContext.Provider
+        value={{
+          appRoot: rootRef,
+          portalRoot: portalRoot,
+          embedded: mode === "embedded",
+          keyboardInput: isKeyboardInputActive,
+          mode,
+        }}
+      >
+        <ScrollContext.Provider value={scrollController}>
+          <IconSettingsProvider
+            classPrefix="vkui"
+            globalClasses={!noLegacyClasses}
+          >
+            {children}
+          </IconSettingsProvider>
+        </ScrollContext.Provider>
+      </AppRootContext.Provider>
+    );
+
+    return mode === "partial" ? (
+      content
+    ) : (
+      <div
+        ref={rootRef}
+        // eslint-disable-next-line vkui/no-object-expression-in-arguments
+        vkuiClass={classNames("AppRoot", {
+          "AppRoot--no-mouse": !hasMouse,
+        })}
+        {...props}
+      >
+        {content}
+      </div>
+    );
+  },
+  {
+    sizeX: true,
+    hasMouse: true,
+  }
+);

package/src/components/AppRoot/AppRootContext.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+
+export interface AppRootContextInterface {
+  appRoot?: React.RefObject<HTMLDivElement>;
+  portalRoot?: HTMLDivElement | null;
+  embedded?: boolean;
+  mode?: "partial" | "embedded" | "full";
+  keyboardInput?: boolean;
+}
+
+export const AppRootContext = React.createContext<AppRootContextInterface>({
+  portalRoot: null,
+});

package/src/components/AppRoot/AppRootPortal.tsx

@@ -0,0 +1,24 @@
+import * as React from "react";
+import { createPortal } from "react-dom";
+import { AppRootContext } from "./AppRootContext";
+import { AppearanceProvider } from "../AppearanceProvider/AppearanceProvider";
+import { useAppearance } from "../../hooks/useAppearance";
+
+export const AppRootPortal: React.FC<
+  React.PropsWithChildren<{ className?: string; forcePortal?: boolean }>
+> = ({ children, className, forcePortal }) => {
+  const { portalRoot, mode } = React.useContext(AppRootContext);
+  const appearance = useAppearance();
+
+  forcePortal = forcePortal ?? mode !== "full";
+  return portalRoot && forcePortal ? (
+    createPortal(
+      <AppearanceProvider appearance={appearance}>
+        <div className={className}>{children}</div>
+      </AppearanceProvider>,
+      portalRoot
+    )
+  ) : (
+    <React.Fragment>{children}</React.Fragment>
+  );
+};

package/src/components/AppRoot/Readme.md

@@ -0,0 +1,9 @@
+Обязательный компонент-обёртка над приложением. В нём инкапсулирована логика [режимов подключения](#/Modes).
+
+## Режимы скролла
+
+Навигационные компоненты VKUI — `Root, View, Panel, Epic` — запоминают скролл экрана и восстанавливают его при возвращении. embedded-приложения поддерживают два режима скролла:
+
+- `global` (по умолчанию) — VKUI-приложение скроллится вместе со страницей.
+- `contain` — VKUI-приложение живет в отдельной зоне и скроллится независимо внутри `AppRoot` (например, в модалке).
+  Режимы переключают через `<AppRoot scroll="...">`.

package/src/components/AppRoot/ScrollContext.ts

@@ -0,0 +1,132 @@
+import * as React from "react";
+import { noop } from "../../lib/utils";
+import { useIsomorphicLayoutEffect } from "../../lib/useIsomorphicLayoutEffect";
+import { clamp } from "../../helpers/math";
+
+const clearDisableScrollStyle = (node: HTMLElement) => {
+  Object.assign(node.style, {
+    position: "",
+    top: "",
+    left: "",
+    right: "",
+    overflowY: "",
+    overflowX: "",
+  });
+};
+
+export interface ScrollContextInterface {
+  getScroll(): { x: number; y: number };
+  scrollTo(x?: number, y?: number): void;
+  enableScrollLock(): void;
+  disableScrollLock(): void;
+}
+
+export const ScrollContext = React.createContext<ScrollContextInterface>({
+  getScroll: () => ({ x: 0, y: 0 }),
+  scrollTo: noop,
+  enableScrollLock: noop,
+  disableScrollLock: noop,
+});
+
+export const useScroll = () => React.useContext(ScrollContext);
+
+export const globalScrollController = (
+  window: Window | undefined,
+  document: HTMLDocument | undefined
+): ScrollContextInterface => ({
+  getScroll: () => ({ x: window!.pageXOffset, y: window!.pageYOffset }),
+  scrollTo: (x = 0, y = 0) => {
+    // Some iOS versions do not normalize scroll — do it manually.
+    window!.scrollTo(
+      x ? clamp(x, 0, document!.body.scrollWidth - window!.innerWidth) : 0,
+      y ? clamp(y, 0, document!.body.scrollHeight - window!.innerHeight) : 0
+    );
+  },
+  enableScrollLock: () => {
+    const scrollY = window!.pageYOffset;
+    const scrollX = window!.pageXOffset;
+    const overflowY =
+      window!.innerWidth > document!.documentElement.clientWidth
+        ? "scroll"
+        : "";
+    const overflowX =
+      window!.innerHeight > document!.documentElement.clientHeight
+        ? "scroll"
+        : "";
+
+    Object.assign(document!.body.style, {
+      position: "fixed",
+      top: `-${scrollY}px`,
+      left: `-${scrollX}px`,
+      right: "0",
+      overflowY,
+      overflowX,
+    });
+  },
+  disableScrollLock: () => {
+    const scrollY = document!.body.style.top;
+    const scrollX = document!.body.style.left;
+
+    clearDisableScrollStyle(document!.body);
+    window!.scrollTo(-parseInt(scrollX || "0"), -parseInt(scrollY || "0"));
+  },
+});
+
+export const elementScrollController = (
+  elRef: React.RefObject<HTMLElement>
+): ScrollContextInterface => ({
+  getScroll: () => ({
+    x: elRef.current?.scrollLeft ?? 0,
+    y: elRef.current?.scrollTop ?? 0,
+  }),
+  scrollTo: (x = 0, y = 0) => {
+    const el = elRef.current;
+    // Some iOS versions do not normalize scroll — do it manually.
+    el?.scrollTo(
+      x ? clamp(x, 0, el.scrollWidth - el.clientWidth) : 0,
+      y ? clamp(y, 0, el.scrollHeight - el.clientHeight) : 0
+    );
+  },
+  enableScrollLock: () => {
+    const el = elRef.current;
+    if (!el) {
+      return;
+    }
+    const scrollY = el.scrollTop;
+    const scrollX = el.scrollLeft;
+    const overflowY = el.scrollWidth > el.clientWidth ? "scroll" : "";
+    const overflowX = el.scrollHeight > el.clientHeight ? "scroll" : "";
+
+    Object.assign(el.style, {
+      position: "absolute",
+      top: `-${scrollY}px`,
+      left: `-${scrollX}px`,
+      right: "0",
+      overflowY,
+      overflowX,
+    });
+  },
+  disableScrollLock: () => {
+    const el = elRef.current;
+    if (!el) {
+      return;
+    }
+
+    const scrollY = el.style.top;
+    const scrollX = el.style.left;
+
+    clearDisableScrollStyle(el);
+    el.scrollTo(-parseInt(scrollX || "0"), -parseInt(scrollY || "0"));
+  },
+});
+
+export const useScrollLock = (enabled = true) => {
+  const { enableScrollLock, disableScrollLock } = useScroll();
+  useIsomorphicLayoutEffect(() => {
+    if (enabled) {
+      enableScrollLock();
+      return disableScrollLock;
+    }
+    return noop;
+  }, [enableScrollLock, disableScrollLock, enabled]);
+};

package/src/components/AppearanceProvider/AppearanceProvider.tsx

@@ -0,0 +1,61 @@
+import * as React from "react";
+import { AppearanceType } from "@vkontakte/vk-bridge";
+import { AppearanceProviderContext } from "./AppearanceProviderContext";
+import { getScheme } from "../../helpers/getScheme";
+import { classNamesString } from "../../lib/classNames";
+import { usePlatform } from "../../hooks/usePlatform";
+import { Platform } from "../../lib/platform";
+
+export interface AppearanceProviderProps {
+  appearance?: AppearanceType;
+}
+
+export const generateVKUITokensClassName = (
+  platform: string,
+  appearance: string
+): string => {
+  let tokensPlatform;
+  switch (platform) {
+    case Platform.ANDROID:
+      tokensPlatform = "vkBase";
+      break;
+    case Platform.IOS:
+      tokensPlatform = "vkIOS";
+      break;
+    case Platform.VKCOM:
+      tokensPlatform = "vkCom";
+      break;
+    default:
+      tokensPlatform = platform;
+  }
+
+  return `vkui--${tokensPlatform}--${appearance}`;
+};
+
+export const AppearanceProvider: React.FC<AppearanceProviderProps> = ({
+  children,
+  appearance = "light",
+}) => {
+  const platform = usePlatform();
+  const scheme = getScheme({
+    platform,
+    appearance,
+  });
+
+  return (
+    <AppearanceProviderContext.Provider value={appearance}>
+      {React.Children.map(children, (child) => {
+        if (React.isValidElement(child)) {
+          return React.cloneElement(child, {
+            className: classNamesString(
+              child.props.className,
+              `vkui${scheme}`,
+              generateVKUITokensClassName(platform, appearance)
+            ),
+          });
+        }
+        return child;
+      })}
+    </AppearanceProviderContext.Provider>
+  );
+};

package/src/components/AppearanceProvider/AppearanceProviderContext.tsx

@@ -0,0 +1,7 @@
+import * as React from "react";
+import { AppearanceType } from "@vkontakte/vk-bridge";
+import { Appearance } from "../../helpers/scheme";
+
+export const AppearanceProviderContext = React.createContext<AppearanceType>(
+  Appearance.LIGHT
+);