@vkontakte/vkui 6.2.1 → 6.3.0

package/src/hooks/useExternRef.ts

@@ -1,26 +1,57 @@
 import * as React from 'react';
 import { setRef } from '../lib/utils';
 
+class ExternalRef<T> implements React.MutableRefObject<T | null> {
+  #element: T | null = null;
+  readonly #externRefs = new Set<React.Ref<T>>();
+
+  constructor(externRefs: Array<React.Ref<T> | undefined | false> = []) {
+    externRefs.forEach((ref) => {
+      if (ref) {
+        this.#externRefs.add(ref);
+      }
+    });
+  }
+
+  updateExternRefs(refs: Array<React.Ref<T> | undefined | false>) {
+    refs.forEach((ref) => {
+      if (!ref || this.#externRefs.has(ref)) {
+        return;
+      }
+
+      setRef(this.#element, ref);
+      this.#externRefs.add(ref);
+    });
+  }
+
+  get current() {
+    return this.#element;
+  }
+
+  set current(el) {
+    this.#element = el;
+    this.#externRefs.forEach((ref) => setRef(el, ref));
+  }
+
+  /**
+   * React проверяет наличие свойства current у объектов через hasOwnProperty
+   *
+   * https://github.com/facebook/react/blob/c3cdbec0a78d39b5ff7329384cb41c4573a38212/packages/react-reconciler/src/ReactFiberCommitWork.js#L1612
+   */
+  hasOwnProperty(v: PropertyKey): v is keyof ExternalRef<T> {
+    return v === 'current';
+  }
+}
+
 export function useExternRef<T>(
   ...externRefs: Array<React.Ref<T> | undefined | false>
 ): React.MutableRefObject<T | null> {
-  const stableRef = React.useRef<T | null>(null);
-
-  return React.useMemo(
-    () => ({
-      get current() {
-        return stableRef.current;
-      },
-      set current(el) {
-        stableRef.current = el;
-        externRefs.forEach((ref) => {
-          if (ref) {
-            setRef(el, ref);
-          }
-        });
-      },
-    }),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    externRefs,
-  );
+  const ref = React.useRef<ExternalRef<T> | null>(null);
+  if (ref.current === null) {
+    ref.current = new ExternalRef(externRefs);
+  } else {
+    ref.current.updateExternRefs(externRefs);
+  }
+
+  return ref.current;
 }

package/src/hooks/useFocusVisible.ts

@@ -1,7 +1,11 @@
 import { FocusEvent, useCallback, useContext, useState } from 'react';
 import { AppRootContext } from '../components/AppRoot/AppRootContext';
 
-export function useFocusVisible(withKeyboardInputCheck = true) {
+export function useFocusVisible(withKeyboardInputCheck = true): {
+  focusVisible: boolean;
+  onFocus: (event: FocusEvent<HTMLElement>) => void;
+  onBlur: (event: FocusEvent<HTMLElement>) => void;
+} {
   const [isFocused, setIsFocused] = useState(false);
   const { keyboardInput } = useContext(AppRootContext);
 

package/src/hooks/useFocusVisibleClassName.ts

@@ -2,7 +2,7 @@ import { classNames } from '@vkontakte/vkjs';
 import { LiteralUnion } from '../types';
 import styles from '../styles/focusVisible.module.css';
 
-export const focusVisiblePresetModeClassNames = {
+export const focusVisiblePresetModeClassNames: Record<'inside' | 'outside', string> = {
   inside: styles['-focus-visible--mode-inside'],
   outside: styles['-focus-visible--mode-outside'],
 };
@@ -35,7 +35,7 @@ export interface UseFocusVisibleClassNameProps {
 export function useFocusVisibleClassName({
   focusVisible = false,
   mode = 'inside',
-}: UseFocusVisibleClassNameProps) {
+}: UseFocusVisibleClassNameProps): string {
   const modeClassName = isPresetMode(mode) ? focusVisiblePresetModeClassNames[mode] : mode;
 
   const focusVisibleClassNames = classNames(

package/src/hooks/useGlobalEscKeyDown.ts

@@ -12,7 +12,10 @@ const EVENT_OPTIONS = {
  *
  * @private
  */
-export const useGlobalEscKeyDown = (init: boolean, callback?: (event: KeyboardEvent) => void) => {
+export const useGlobalEscKeyDown = (
+  init: boolean,
+  callback?: (event: KeyboardEvent) => void,
+): void => {
   const { document } = useDOM();
   useIsomorphicLayoutEffect(() => {
     if (!document || !init || !callback) {

package/src/hooks/useGlobalOnClickOutside.ts

@@ -13,7 +13,7 @@ export const useGlobalOnClickOutside = <
 >(
   callback: (event: MouseEvent) => void,
   ...refs: T[]
-) => {
+): void => {
   const { document } = useDOM();
   useIsomorphicLayoutEffect(() => {
     const someRefNotNull = refs.some((ref) => ref && ref.current !== null);

package/src/hooks/useIsClient.ts

@@ -9,7 +9,7 @@ import { useIsomorphicLayoutEffect } from '../lib/useIsomorphicLayoutEffect';
  *
  * @see {@link https://beta.reactjs.org/apis/react-dom/hydrate#handling-different-client-and-server-content React Docs}
  */
-export function useIsClient(initial = false) {
+export function useIsClient(initial = false): boolean {
   const [isClient, setIsClient] = React.useState(initial);
 
   useIsomorphicLayoutEffect(() => {

package/src/hooks/useMediaQueries.ts

@@ -20,7 +20,7 @@ function getMediaQueries(matchMedia: (query: string) => MediaQueryList): MediaQu
 /**
  * Возвращает медиа выражения определенные дизайн-системой.
  */
-export const useMediaQueries = () => {
+export const useMediaQueries = (): MediaQueries => {
   const { window } = useDOM();
 
   return React.useMemo<MediaQueries>(

package/src/hooks/useNativeFormResetListener.ts

@@ -4,7 +4,7 @@ import { useIsomorphicLayoutEffect } from '../lib/useIsomorphicLayoutEffect';
 export const useNativeFormResetListener = (
   ref: React.RefObject<HTMLElement>,
   handler: (event: Event) => void,
-) => {
+): void => {
   useIsomorphicLayoutEffect(() => {
     if (!ref.current) {
       return;

package/src/hooks/useResizeObserver.ts

@@ -9,7 +9,7 @@ import { useStableCallback } from './useStableCallback';
 export function useResizeObserver(
   ref: React.MutableRefObject<HTMLElement | null> | React.RefObject<HTMLElement | null> | null,
   callback: (element: HTMLElement) => void,
-) {
+): void {
   const stableCallback = useStableCallback(callback);
 
   useEffect(

package/src/hooks/useTodayDate.ts

@@ -11,7 +11,7 @@ import { useDOM } from '../lib/dom';
  *
  * @param listenDayChangesForUpdate - флаг по которому определяется, будет ли создаваться подписка на смену календарного дня
  */
-export function useTodayDate(listenDayChangesForUpdate = false) {
+export function useTodayDate(listenDayChangesForUpdate = false): Date {
   const { document, window } = useDOM();
   const [todayDate, setTodayDate] = React.useState(() => new Date());
 

package/src/hooks/useWaitTransitionFinish.ts

@@ -2,7 +2,11 @@ import * as React from 'react';
 import { noop } from '@vkontakte/vkjs';
 import { useDOM } from '../lib/dom';
 
-export const useWaitTransitionFinish = () => {
+export const useWaitTransitionFinish = (): ((
+  element: HTMLElement | undefined | null,
+  eventHandler: VoidFunction,
+  durationFallback: number,
+) => void) => {
   const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
   const { document } = useDOM();
   const detach = React.useRef(noop);

package/src/index.ts

@@ -106,6 +106,8 @@ export { AspectRatio } from './components/AspectRatio/AspectRatio';
 export type { AspectRatioProps } from './components/AspectRatio/AspectRatio';
 export { Flex } from './components/Flex/Flex';
 export type { FlexProps } from './components/Flex/Flex';
+export { SimpleGrid } from './components/SimpleGrid/SimpleGrid';
+export type { SimpleGridProps } from './components/SimpleGrid/SimpleGrid';
 
 /**
  * Popouts
@@ -203,7 +205,7 @@ export type { ImageProps, ImageBadgeProps, ImageOverlayProps } from './component
 export { Progress } from './components/Progress/Progress';
 export type { ProgressProps } from './components/Progress/Progress';
 export { Search } from './components/Search/Search';
-export type { SearchProps } from './components/Search/Search';
+export type { SearchProps, RenderIconButtonFn } from './components/Search/Search';
 export { Tabs } from './components/Tabs/Tabs';
 export type { TabsProps } from './components/Tabs/Tabs';
 export { TabsItem } from './components/TabsItem/TabsItem';
@@ -222,7 +224,11 @@ export { OnboardingTooltipContainer } from './components/OnboardingTooltip/Onboa
 export { Counter } from './components/Counter/Counter';
 export type { CounterProps } from './components/Counter/Counter';
 export { UsersStack } from './components/UsersStack/UsersStack';
-export type { UsersStackProps } from './components/UsersStack/UsersStack';
+export type {
+  UsersStackProps,
+  UsersStackPhoto,
+  UsersStackRenderWrapperProps,
+} from './components/UsersStack/UsersStack';
 export { Separator } from './components/Separator/Separator';
 export type { SeparatorProps } from './components/Separator/Separator';
 export { Spacing } from './components/Spacing/Spacing';
@@ -266,7 +272,7 @@ export type { FormItemTopLabelProps } from './components/FormItem/FormItemTop/Fo
 export type { FormItemTopAsideProps } from './components/FormItem/FormItemTop/FormItemTopAside';
 export type { FormItemProps } from './components/FormItem/FormItem';
 export { FormField } from './components/FormField/FormField';
-export type { FormFieldProps } from './components/FormField/FormField';
+export type { FormFieldProps, FieldIconsAlign } from './components/FormField/FormField';
 export { FormLayoutGroup } from './components/FormLayoutGroup/FormLayoutGroup';
 export type { FormLayoutGroupProps } from './components/FormLayoutGroup/FormLayoutGroup';
 export { FormStatus } from './components/FormStatus/FormStatus';
@@ -285,6 +291,7 @@ export { ChipsInput } from './components/ChipsInput/ChipsInput';
 export type { ChipsInputProps } from './components/ChipsInput/ChipsInput';
 export { ChipsSelect } from './components/ChipsSelect/ChipsSelect';
 export type { ChipsSelectProps } from './components/ChipsSelect/ChipsSelect';
+export type { FormFieldClearButtonProps } from './components/FormFieldClearButton/FormFieldClearButton';
 export { Slider } from './components/Slider/Slider';
 export type { SliderBaseProps, SliderProps, SliderMultipleProps } from './components/Slider/Slider';
 export { Textarea } from './components/Textarea/Textarea';

package/src/lib/SSR.tsx

@@ -14,7 +14,7 @@ export interface SSRWrapperProps {
 /**
  * @see https://vkcom.github.io/VKUI/#/SSR
  */
-export const SSRWrapper = ({ userAgent, browserInfo, children }: SSRWrapperProps) => {
+export const SSRWrapper: React.FC<SSRWrapperProps> = ({ userAgent, browserInfo, children }) => {
   if (!browserInfo && userAgent) {
     browserInfo = computeBrowserInfo(userAgent);
   }

package/src/lib/accessibility.ts

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { HasChildren, ValuesOfObject } from '../types';
 import { getTextFromChildren } from './children';
 
-export const FOCUSABLE_ELEMENTS_LIST = [
+export const FOCUSABLE_ELEMENTS_LIST: string[] = [
   'a[href]',
   'area[href]',
   'input:not([disabled]):not([hidden]):not([type="hidden"]):not([aria-hidden])',
@@ -52,12 +52,27 @@ const EVENT_KEY_TO_COMMON_KEY_MAP = new Map([
   ['PageDown', Keys.PAGE_DOWN],
 ]);
 
-export function pressedKey<T extends KeyboardEvent | React.KeyboardEvent>(event: T) {
+export function pressedKey<T extends KeyboardEvent | React.KeyboardEvent>(
+  event: T,
+):
+  | 'Enter'
+  | 'Space'
+  | 'Tab'
+  | 'Escape'
+  | 'Home'
+  | 'End'
+  | 'ArrowLeft'
+  | 'ArrowRight'
+  | 'ArrowUp'
+  | 'ArrowDown'
+  | 'PageUp'
+  | 'PageDown'
+  | null {
   const foundKey = EVENT_KEY_TO_COMMON_KEY_MAP.get(event.key);
   return foundKey ? foundKey : null;
 }
 
-export const FOCUS_ALLOW_LIST_KEYS = new Set<string>([
+export const FOCUS_ALLOW_LIST_KEYS: Set<string> = new Set<string>([
   Keys.TAB,
   Keys.ARROW_LEFT,
   Keys.ARROW_RIGHT,
@@ -67,13 +82,15 @@ export const FOCUS_ALLOW_LIST_KEYS = new Set<string>([
   Keys.DELETE,
 ]);
 
-export function isKeyboardFocusingStarted<T extends KeyboardEvent | React.KeyboardEvent>(event: T) {
+export function isKeyboardFocusingStarted<T extends KeyboardEvent | React.KeyboardEvent>(
+  event: T,
+): boolean {
   return FOCUS_ALLOW_LIST_KEYS.has(event.key);
 }
 
 export function shouldTriggerClickOnEnterOrSpace(
   e: KeyboardEvent | React.KeyboardEvent<HTMLElement>,
-) {
+): boolean {
   const el = e.target as HTMLElement;
   const { tagName } = el;
 
@@ -104,7 +121,7 @@ export const injectAriaExpandedPropByRole = (
   props: React.ComponentProps<any>,
   state: boolean,
   role?: React.AriaRole,
-) => {
+): React.ComponentProps<any> => {
   switch (role) {
     case 'dialog':
     case 'menu':
@@ -131,7 +148,7 @@ export function hasAccessibleName({
   'aria-labelledby': ariaLabelledBy,
   title,
   children,
-}: HasAccessibleNameProps) {
+}: HasAccessibleNameProps): boolean {
   if (ariaLabel || ariaLabelledBy || title) {
     return true;
   }
@@ -150,7 +167,7 @@ export function hasAccessibleName({
  */
 export const getHorizontalFocusGoTo = (
   keys: Extract<KeysValues, 'ArrowUp' | 'ArrowLeft' | 'ArrowDown' | 'ArrowRight'>,
-) => {
+): 'prev' | 'next' => {
   switch (keys) {
     case Keys.ARROW_UP:
     case Keys.ARROW_LEFT:

package/src/{shared/breakpoints.js → lib/adaptivity/breakpoints.ts}

@@ -1,41 +1,23 @@
-/**
- * Храним брейкпоинты в JS файле для синхронизации значений между TS и CSS.
- *
- * @type {{
- *  DESKTOP: 1280,
- *  TABLET: 1024,
- *  SMALL_TABLET: 768,
- *  MOBILE: 320,
- *  MOBILE_LANDSCAPE_HEIGHT: 415,
- *  MEDIUM_HEIGHT: 720
- * }}
- */
-const BREAKPOINTS = {
+export const BREAKPOINTS = {
   DESKTOP: 1280,
   TABLET: 1024,
   SMALL_TABLET: 768,
   MOBILE: 320,
   MOBILE_LANDSCAPE_HEIGHT: 415,
   MEDIUM_HEIGHT: 720,
-};
+} as const;
 
 /**
  * Луч [a;+∞)
- *
- * @param {number} a
- * @returns {string}
  */
-function widthPlus(a) {
+export function widthPlus(a: number): string {
   return `(min-width: ${a}px)`;
 }
 
 /**
  * Открытый луч (-∞;b)
- *
- * @param {number} b
- * @returns {string}
  */
-function widthMinus(b) {
+export function widthMinus(b: number): string {
   // NOTE: `not` плохо поддерживается, поэтому используем max-width и вычитаем
   // от числа 0.1
   return `(max-width: ${b - 0.1}px)`;
@@ -43,32 +25,22 @@ function widthMinus(b) {
 
 /**
  * Полуинтервал [a;b)
- *
- * @param {number} a
- * @param {number} b
- * @returns {string}
  */
-function widthHalfInterval(a, b) {
+export function widthHalfInterval(a: number, b: number): string {
   return `${widthPlus(a)} and ${widthMinus(b)}`;
 }
 
 /**
  * Луч [a;+∞)
- *
- * @param {number} a
- * @returns {string}
  */
-function heightPlus(a) {
+export function heightPlus(a: number): string {
   return `(min-height: ${a}px)`;
 }
 
 /**
  * Открытый луч (-∞;b)
- *
- * @param {number} b
- * @returns {string}
  */
-function heightMinus(b) {
+export function heightMinus(b: number): string {
   // NOTE: `not` плохо поддерживается, поэтому используем max-width и вычитаем
   // от числа 0.1
   return `(max-height: ${b - 0.1}px)`;
@@ -76,16 +48,12 @@ function heightMinus(b) {
 
 /**
  * Полуинтервал [a;b)
- *
- * @param {number} a
- * @param {number} b
- * @returns {string}
  */
-function heightHalfInterval(a, b) {
+export function heightHalfInterval(a: number, b: number): string {
   return `${heightPlus(a)} and ${heightMinus(b)}`;
 }
 
-const MEDIA_QUERIES = {
+export const MEDIA_QUERIES = {
   DESKTOP_PLUS: widthPlus(BREAKPOINTS.DESKTOP),
 
   TABLET: widthHalfInterval(BREAKPOINTS.TABLET, BREAKPOINTS.DESKTOP),
@@ -98,15 +66,4 @@ const MEDIA_QUERIES = {
   MEDIUM_HEIGHT: heightPlus(BREAKPOINTS.MEDIUM_HEIGHT),
 
   MOBILE_LANDSCAPE_HEIGHT: heightPlus(BREAKPOINTS.MOBILE_LANDSCAPE_HEIGHT),
-};
-
-module.exports = {
-  BREAKPOINTS,
-  MEDIA_QUERIES,
-  widthHalfInterval,
-  widthPlus,
-  widthMinus,
-  heightHalfInterval,
-  heightPlus,
-  heightMinus,
-};
+} as const;

package/src/lib/adaptivity/constants.ts

@@ -1,7 +1,5 @@
 import { ValuesOfObject } from '../../types';
 
-export { BREAKPOINTS, MEDIA_QUERIES } from '../../shared/breakpoints';
-
 /**
  * Public API.
  * Брейкпоинты на ширину.
@@ -47,7 +45,10 @@ export const SizeType = {
 
 export type SizeTypeValues = ValuesOfObject<typeof SizeType>;
 
-export const VIEW_WIDTH_TO_CSS_BREAKPOINT_MAP = {
+export const VIEW_WIDTH_TO_CSS_BREAKPOINT_MAP: Record<
+  ViewWidthType,
+  'smallMobileMinus' | 'mobile' | 'smallTablet' | 'tablet' | 'desktopPlus'
+> = {
   [ViewWidth.SMALL_MOBILE]: 'smallMobileMinus',
   [ViewWidth.MOBILE]: 'mobile',
   [ViewWidth.SMALL_TABLET]: 'smallTablet',

package/src/lib/adaptivity/functions.ts

@@ -1,7 +1,7 @@
 import type { Exact } from '../../types';
 import { type PlatformType } from '../platform';
+import { BREAKPOINTS } from './breakpoints';
 import {
-  BREAKPOINTS,
   SizeTypeValues,
   VIEW_WIDTH_TO_CSS_BREAKPOINT_MAP,
   ViewHeight,
@@ -14,7 +14,7 @@ import type { CSSBreakpointsClassNames, MediaQueries } from './types';
 /**
  * @public
  */
-export function getViewWidthByViewportWidth(viewportWidth: number) {
+export function getViewWidthByViewportWidth(viewportWidth: number): ViewWidthType {
   if (viewportWidth >= BREAKPOINTS.DESKTOP) {
     return ViewWidth.DESKTOP;
   }
@@ -51,7 +51,7 @@ export function getViewWidthByMediaQueries(mediaQueries: MediaQueries): ViewWidt
 /**
  * @public
  */
-export function getViewHeightByViewportHeight(viewportHeight: number) {
+export function getViewHeightByViewportHeight(viewportHeight: number): ViewHeightType {
   if (viewportHeight >= BREAKPOINTS.MEDIUM_HEIGHT) {
     return ViewHeight.MEDIUM;
   }
@@ -77,11 +77,14 @@ export function getSizeX(viewWidth: ViewWidthType): SizeTypeValues {
   return viewWidth <= ViewWidth.MOBILE ? 'compact' : 'regular';
 }
 
-export function isCompactByViewWidth(viewWidth: ViewWidthType | undefined, hasPointer?: boolean) {
+export function isCompactByViewWidth(
+  viewWidth: ViewWidthType | undefined,
+  hasPointer?: boolean,
+): boolean | undefined {
   return viewWidth !== undefined && viewWidth >= ViewWidth.SMALL_TABLET && hasPointer;
 }
 
-export function isCompactByViewHeight(viewHeight: ViewHeightType | undefined) {
+export function isCompactByViewHeight(viewHeight: ViewHeightType | undefined): boolean {
   return viewHeight !== undefined && viewHeight <= ViewHeight.EXTRA_SMALL;
 }
 

package/src/lib/adaptivity/index.ts

@@ -1,3 +1,4 @@
-export type { CSSBreakpoints, JSBreakpoints, MediaQueries } from './types';
+export type { CSSBreakpoints, JSBreakpoints, MediaQueries, CSSCustomMedias } from './types';
 export * from './constants';
+export { BREAKPOINTS, MEDIA_QUERIES } from './breakpoints';
 export * from './functions';

package/src/lib/adaptivity/types.ts

@@ -1,8 +1,6 @@
-/**
- * Соответствуют тому, что генерирует функция `getCustomMedias()`.
- *
- * {@link import('../../../shared.config.js') ../../../shared.config.js}
- */
+import type { ValuesOfObject } from '../../types';
+import type { SizeType } from './constants';
+
 export type CSSBreakpoints =
   | 'desktopPlus'
   | 'tabletPlus'
@@ -31,3 +29,23 @@ export type JSBreakpoints =
   | 'mobileLandscapeHeight';
 
 export type MediaQueries = Record<JSBreakpoints, MediaQueryList>;
+
+type SizeTypeValue = ValuesOfObject<typeof SizeType>;
+
+/**
+ * Используется в `packages/vkui/scripts/generateCSSCustomMedias.mjs`, который отвечает за генерацию
+ * `packages/vkui/styles/customMedias.generated.css`.
+ */
+export type CSSCustomMedias = Record<
+  | `--sizeX-${SizeTypeValue}`
+  | `--sizeY-${SizeTypeValue}`
+  | `--viewWidth-${CSSBreakpoints}`
+  | '--hover-has'
+  | '--hover-has-not'
+  | '--pointer-has'
+  | '--pointer-has-not'
+  | '--reduce-motion'
+  | '--desktop'
+  | '--mobile',
+  string
+>;

package/src/lib/animation/fades.ts

@@ -1,6 +1,6 @@
 import styles from '../../styles/animationFades.module.css'; // eslint-disable-line import/order
 
-export const animationFadeClassNames = {
+export const animationFadeClassNames: Record<'in' | 'out', string> = {
   in: styles['-anim-fade-in'],
   out: styles['-anim-fade-out'],
-} as const;
+};

package/src/lib/animation/rubberbandIfOutOfBounds.ts

@@ -18,7 +18,7 @@ export function rubberbandIfOutOfBounds(
   min: number,
   max: number,
   constant = 0.15,
-) {
+): number {
   if (constant === 0) {
     return clamp(position, min, max);
   }