@vkontakte/vkui 7.2.0 → 7.3.0

package/src/components/CalendarDays/CalendarDays.tsx

@@ -3,7 +3,6 @@
 import * as React from 'react';
 import { classNames } from '@vkontakte/vkjs';
 import { isSameDay, isSameMonth } from 'date-fns';
-import { useExternRef } from '../../hooks/useExternRef';
 import { useTodayDate } from '../../hooks/useTodayDate';
 import { getDaysNames, getWeeks } from '../../lib/calendar';
 import type { HTMLAttributesWithRootRef } from '../../types';
@@ -16,11 +15,12 @@ import {
 import { useConfigProvider } from '../ConfigProvider/ConfigProviderContext';
 import { RootComponent } from '../RootComponent/RootComponent';
 import { Footnote } from '../Typography/Footnote/Footnote';
+import { VisuallyHidden } from '../VisuallyHidden/VisuallyHidden';
 import styles from './CalendarDays.module.css';
 
 export type CalendarDaysTestsProps = {
   /**
-   * Передает атрибут `data-testid` для дня в календаре
+   * Передает атрибут `data-testid` для дня в календаре.
    */
   dayTestId?: CalendarDayTestsProps['testId'];
 };
@@ -29,25 +29,90 @@ export interface CalendarDaysProps
   extends Omit<HTMLAttributesWithRootRef<HTMLDivElement>, 'onChange'>,
     Pick<CalendarDayProps, 'renderDayContent'>,
     CalendarDaysTestsProps {
-  value?: Date | Array<Date | null>;
+  /**
+   * Выбранная дата или диапазон дат.
+   */
+  value?: Date | Array<Date | null> | null;
+  /**
+   * Дата, определяющая отображаемый месяц.
+   */
   viewDate: Date;
+  /**
+   * День недели, с которого начинается неделя (0 - воскресенье, 6 - суббота).
+   */
   weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /**
+   * Показывать дни соседних месяцев.
+   */
   showNeighboringMonth?: boolean;
+  /**
+   * Размер календаря.
+   */
   size?: 's' | 'm';
+  /**
+   * Дополнительные свойства для элементов дней.
+   */
   dayProps?: CalendarDayElementProps;
+  /**
+   * Следить за изменениями дней для обновления UI.
+   */
   listenDayChangesForUpdate?: boolean;
+  /**
+   * Обработчик изменения выбранного дня.
+   */
   onDayChange: (value: Date) => void;
+  /**
+   * Проверяет, заблокирован ли день для выбора.
+   */
   isDayDisabled: (value: Date) => boolean;
+  /**
+   * Определяет, является ли день началом выделенного диапазона.
+   */
   isDaySelectionStart: (value: Date, dayOfWeek: number) => boolean;
+  /**
+   * Определяет, является ли день концом выделенного диапазона.
+   */
   isDaySelectionEnd: (value: Date, dayOfWeek: number) => boolean;
+  /**
+   * Определяет начало диапазона при наведении (подсветка).
+   */
   isHintedDaySelectionStart?: (value: Date, dayOfWeek: number) => boolean;
+  /**
+   * Определяет конец диапазона при наведении (подсветка).
+   */
   isHintedDaySelectionEnd?: (value: Date, dayOfWeek: number) => boolean;
+  /**
+   * Проверяет, является ли день активным (текущая дата).
+   */
   isDayActive: (value: Date) => boolean;
+  /**
+   * Проверяет, подсвечен ли день (при наведении).
+   */
   isDayHinted?: (value: Date) => boolean;
+  /**
+   * Проверяет, возможно ли сфокусироваться на дне с клавиатуры.
+   */
+  isDayFocusable?: (value: Date) => boolean;
+  /**
+   * Проверяет, выбран ли день.
+   */
   isDaySelected?: (value: Date) => boolean;
+  /**
+   * Проверяет, находится ли день в фокусе.
+   */
   isDayFocused: (value: Date) => boolean;
+  /**
+   * Обработчик события 'pointerenter' на элементе дня.
+   */
   onDayEnter?: (value: Date) => void;
+  /**
+   * Обработчик события 'pointerleave' на элементе дня.
+   */
   onDayLeave?: (value: Date) => void;
+  /**
+   * Обработчик события `focus` на элементе дня.
+   */
+  onDayFocus?: (value: Date) => void;
 }
 
 export const CalendarDays = ({
@@ -61,10 +126,12 @@ export const CalendarDays = ({
   isDaySelectionStart,
   onDayEnter,
   onDayLeave,
+  onDayFocus,
   isDayHinted,
   isHintedDaySelectionStart,
   isHintedDaySelectionEnd,
   isDayFocused,
+  isDayFocusable,
   isDayDisabled,
   size,
   showNeighboringMonth = false,
@@ -76,7 +143,6 @@ export const CalendarDays = ({
   ...props
 }: CalendarDaysProps): React.ReactNode => {
   const { locale } = useConfigProvider();
-  const ref = useExternRef(getRootRef);
   const now = useTodayDate(listenDayChangesForUpdate);
 
   const weeks = React.useMemo(() => getWeeks(viewDate, weekStartsOn), [weekStartsOn, viewDate]);
@@ -89,55 +155,106 @@ export const CalendarDays = ({
   const handleDayChange = React.useCallback(
     (date: Date) => {
       onDayChange(date);
-
-      ref.current?.focus();
     },
-    [onDayChange, ref],
+    [onDayChange],
   );
 
-  return (
-    <RootComponent {...props} baseClassName={styles.host} getRootRef={ref}>
-      <div className={classNames(styles.row, size === 's' && styles.rowSizeS)}>
-        {daysNames.map((dayName) => (
-          <Footnote key={dayName} className={styles.weekday}>
-            {dayName}
-          </Footnote>
-        ))}
-      </div>
+  const viewDateLabelId = React.useId();
+  const currentMonthLabel = value
+    ? new Intl.DateTimeFormat(locale, {
+        year: 'numeric',
+        month: 'long',
+      }).format(viewDate)
+    : null;
 
-      {weeks.map((week, i) => (
-        <div className={classNames(styles.row, size === 's' && styles.rowSizeS)} key={i}>
-          {week.map((day, i) => {
-            const sameMonth = isSameMonth(day, viewDate);
-            return (
-              <CalendarDay
-                key={day.toISOString()}
-                day={day}
-                today={isSameDay(day, now)}
-                active={isDayActive(day)}
-                onChange={handleDayChange}
-                hidden={!showNeighboringMonth && !sameMonth}
-                disabled={isDayDisabled(day)}
-                selectionStart={isDaySelectionStart(day, i)}
-                selectionEnd={isDaySelectionEnd(day, i)}
-                hintedSelectionStart={isHintedDaySelectionStart?.(day, i)}
-                hintedSelectionEnd={isHintedDaySelectionEnd?.(day, i)}
-                selected={isDaySelected?.(day)}
-                focused={isDayFocused(day)}
-                onEnter={onDayEnter}
-                onLeave={onDayLeave}
-                hinted={isDayHinted?.(day)}
-                sameMonth={sameMonth}
-                size={size}
-                renderDayContent={renderDayContent}
-                testId={dayTestId}
-                {...dayProps}
-                className={classNames(dayProps?.className, styles.rowDay)}
-              />
-            );
-          })}
+  return (
+    <React.Fragment>
+      {/*
+       * Нельзя помещать текст currentMonthLabel внутрь role="grid" или с помощью aria-label,
+       * иначе пользователи NVDA не смогут ходить по таблице
+       * с помощью горячих клавиш <Ctrl+Alt+стрелочки>.
+       * Имеется ввиду связка (применение которой визуально не видно):
+       * - из заголовка календаря прыжок в таблицу с помощью клавиши <T>
+       * - переход по ячейкам с помощью <Ctrl+Alrt+стрелочки>
+       * NVDA будет говорить, что пользователь вне ячейки таблицы.
+       * Также важно оставить aria-live="polite". Так NVDA зачитывает текущий
+       * месяц и год при переключении месяца и года в заголовке календаря.
+       */}
+      <VisuallyHidden aria-live="polite" id={viewDateLabelId}>
+        {currentMonthLabel}
+      </VisuallyHidden>
+      <RootComponent
+        role="grid"
+        {...props}
+        baseClassName={styles.host}
+        aria-labelledby={viewDateLabelId}
+      >
+        <div
+          role="row"
+          aria-rowindex={1}
+          className={classNames(styles.row, size === 's' && styles.rowSizeS)}
+        >
+          {daysNames.map(({ short: shortDayName, long: longDayName }) => (
+            <Footnote
+              role="columnheader"
+              aria-label={longDayName}
+              key={shortDayName}
+              className={styles.weekday}
+            >
+              {shortDayName}
+            </Footnote>
+          ))}
         </div>
-      ))}
-    </RootComponent>
+
+        {weeks.map((week, i) => (
+          <div
+            role="row"
+            aria-rowindex={i + 2}
+            className={classNames(styles.row, size === 's' && styles.rowSizeS)}
+            key={i}
+          >
+            {week.map((day, i) => {
+              const sameMonth = isSameMonth(day, viewDate);
+              const isHidden = !showNeighboringMonth && !sameMonth;
+              const isToday = isSameDay(day, now);
+              const isActive = isDayActive(day);
+              const isFocused = isDayFocused(day);
+              return (
+                <CalendarDay
+                  role="gridcell"
+                  aria-current={isToday ? 'date' : undefined}
+                  aria-selected={isActive ? 'true' : 'false'}
+                  aria-colindex={i + 1}
+                  tabIndex={isDayFocusable?.(day) ? 0 : -1}
+                  key={day.toISOString()}
+                  day={day}
+                  today={isToday}
+                  active={isActive}
+                  onChange={handleDayChange}
+                  hidden={isHidden}
+                  disabled={isDayDisabled(day)}
+                  selectionStart={isDaySelectionStart(day, i)}
+                  selectionEnd={isDaySelectionEnd(day, i)}
+                  hintedSelectionStart={isHintedDaySelectionStart?.(day, i)}
+                  hintedSelectionEnd={isHintedDaySelectionEnd?.(day, i)}
+                  selected={isDaySelected?.(day)}
+                  focused={isFocused}
+                  onEnter={onDayEnter}
+                  onLeave={onDayLeave}
+                  onFocus={onDayFocus}
+                  hinted={isDayHinted?.(day)}
+                  sameMonth={sameMonth}
+                  size={size}
+                  renderDayContent={renderDayContent}
+                  testId={dayTestId}
+                  {...dayProps}
+                  className={classNames(dayProps?.className, styles.rowDay)}
+                />
+              );
+            })}
+          </div>
+        ))}
+      </RootComponent>
+    </React.Fragment>
   );
 };

package/src/components/CalendarHeader/CalendarHeader.module.css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["./CalendarHeader.module.css"],"names":["host","pickers","picker","navIcon","navIconAccent","navIconNext","navIconPrev","month"],"mappings":"AAAA;AAAA,E,aAAAA,M,WAAA;AAAA,E,aAQAC,S,WARA;AAAA,E,aAcAC,Q,WAdA;AAAA,E,aAcUA,Q,WAdV;AAAA,E,aAkBAC,S,WAlBA;AAAA,E,aA0BAC,e,WA1BA;AAAA,E,aA8BAC,a,WA9BA;AAAA,E,aAkCAC,a,WAlCA;AAAA,E,aAsCAC,O,WAtCA;AAAA;AAAA","file":"CalendarHeader.module.css.d.ts","sourceRoot":""}

package/src/components/CalendarHeader/CalendarHeader.tsx

@@ -24,19 +24,19 @@ type ArrowMonthProps = Omit<React.AllHTMLAttributes<HTMLElement>, 'onClick' | 'a
 
 export type CalendarHeaderTestsProps = {
   /**
-   * Передает атрибут `data-testid` для дропдауна выбора месяца в заголовке календаря
+   * Передает атрибут `data-testid` для дропдауна выбора месяца в заголовке календаря.
    */
   monthDropdownTestId?: string | ((monthIndex: number) => string);
   /**
-   * Передает атрибут `data-testid` для дропдауна выбора года в заголовке календаря
+   * Передает атрибут `data-testid` для дропдауна выбора года в заголовке календаря.
    */
   yearDropdownTestId?: string | ((year: number) => string);
   /**
-   * Передает атрибут `data-testid` для кнопки перехода к следующему месяцу в заголовке календаря
+   * Передает атрибут `data-testid` для кнопки перехода к следующему месяцу в заголовке календаря.
    */
   nextMonthButtonTestId?: string;
   /**
-   * Передает атрибут `data-testid` для кнопки перехода к предыдущему месяцу в заголовке календаря
+   * Передает атрибут `data-testid` для кнопки перехода к предыдущему месяцу в заголовке календаря.
    */
   prevMonthButtonTestId?: string;
 };
@@ -44,26 +44,65 @@ export type CalendarHeaderTestsProps = {
 export interface CalendarHeaderProps
   extends Omit<HTMLAttributesWithRootRef<HTMLDivElement>, 'onChange'>,
     CalendarHeaderTestsProps {
+  /**
+   * Отображаемая дата.
+   */
   viewDate: Date;
   /**
-   * Скрывает иконку для переключения на предыдущий месяц
+   * Скрывает иконку для переключения на предыдущий месяц.
    */
   prevMonthHidden?: boolean;
   /**
-   * Скрывает иконку для переключения на следующий месяц
+   * Скрывает иконку для переключения на следующий месяц.
    */
   nextMonthHidden?: boolean;
+  /**
+   * Отключает селекторы выбора месяца/года.
+   */
   disablePickers?: boolean;
+  /**
+   * `aria-label` для кнопки предыдущего месяца.
+   */
   prevMonthLabel?: string;
+  /**
+   * `aria-label` для кнопки следующего месяца.
+   */
   nextMonthLabel?: string;
+  /**
+   * `aria-label` для селектора месяца.
+   */
   changeMonthLabel?: string;
+  /**
+   * `aria-label` для селектора года.
+   */
   changeYearLabel?: string;
+  /**
+   * Кастомная иконка для кнопки предыдущего месяца.
+   */
   prevMonthIcon?: React.ReactNode;
+  /**
+   * Кастомная иконка для кнопки следующего месяца.
+   */
   nextMonthIcon?: React.ReactNode;
+  /**
+   * Дополнительные свойства для кнопки предыдущего месяца.
+   */
   prevMonthProps?: ArrowMonthProps;
+  /**
+   * Дополнительные свойства для кнопки следующего месяца.
+   */
   nextMonthProps?: ArrowMonthProps;
+  /**
+   * Функция для проверки блокировки месяца.
+   */
   isMonthDisabled?: (monthNumber: number, year?: number) => boolean;
+  /**
+   * Функция для проверки блокировки года.
+   */
   isYearDisabled?: (yearNumber: number) => boolean;
+  /**
+   * Обработчик изменения отображаемой даты.
+   */
   onChange: (viewDate: Date) => void;
   /**
    * Нажатие на кнопку переключения на следующий месяц.
@@ -164,6 +203,15 @@ export const CalendarHeader = ({
     );
   }
 
+  const stopPropogationOfEscapeKeyboardEventWhenSelectIsOpen = React.useCallback(
+    (event: React.KeyboardEvent, isOpen: boolean) => {
+      if (isOpen && event.key === 'Escape') {
+        event.stopPropagation();
+      }
+    },
+    [],
+  );
+
   return (
     <RootComponent baseClassName={styles.host} {...restProps}>
       {!prevMonthHidden && (
@@ -215,6 +263,7 @@ export const CalendarHeader = ({
                   ? monthDropdownTestId
                   : monthDropdownTestId?.(currentMonth)
               }
+              onInputKeyDown={stopPropogationOfEscapeKeyboardEventWhenSelectIsOpen}
             />
             <CustomSelect
               className={classNames(styles.picker, 'vkuiInternalCalendarHeader__picker')}
@@ -228,6 +277,7 @@ export const CalendarHeader = ({
               selectType="accent"
               aria-label={changeYearLabel}
               data-testid={yearDropdownTestId}
+              onInputKeyDown={stopPropogationOfEscapeKeyboardEventWhenSelectIsOpen}
             />
           </div>
         </AdaptivityProvider>

package/src/components/CalendarRange/CalendarRange.module.css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["./CalendarRange.module.css"],"names":["host","inner","header"],"mappings":"AAAA;AAAA,E,aAAAA,M,WAAA;AAAA,E,aAaAC,O,WAbA;AAAA,E,aAmBAA,O,WAnBA;AAAA,E,aAuBAC,Q,WAvBA;AAAA;AAAA","file":"CalendarRange.module.css.d.ts","sourceRoot":""}

package/src/components/CalendarRange/CalendarRange.tsx

@@ -15,6 +15,7 @@ import {
 import { useCalendar } from '../../hooks/useCalendar';
 import { useCustomEnsuredControl } from '../../hooks/useEnsuredControl';
 import { isFirstDay, isLastDay, navigateDate } from '../../lib/calendar';
+import { isHTMLElement } from '../../lib/dom';
 import type { HTMLAttributesWithRootRef } from '../../types';
 import {
   CalendarDays,
@@ -33,11 +34,11 @@ export type DateRangeType = [Date | null, Date | null];
 
 export type CalendarRangeTestsProps = CalendarDaysTestsProps & {
   /**
-   * Передает атрибуты `data-testid` для интерактивных элементов в заголовке календаря в левой части
+   * Передает атрибуты `data-testid` для интерактивных элементов в заголовке календаря в левой части.
    */
   leftPartHeaderTestsData?: CalendarHeaderTestsProps;
   /**
-   * Передает атрибуты `data-testid` для интерактивных элементов в заголовке календаря в правой части
+   * Передает атрибуты `data-testid` для интерактивных элементов в заголовке календаря в правой части.
    */
   rightPartHeaderTestsData?: CalendarHeaderTestsProps;
 };
@@ -55,19 +56,51 @@ export interface CalendarRangeProps
     >,
     Pick<CalendarDaysProps, 'listenDayChangesForUpdate' | 'renderDayContent'>,
     CalendarRangeTestsProps {
-  value?: DateRangeType;
-  defaultValue?: DateRangeType;
+  /**
+   * Текущий выбранный промежуток.
+   */
+  value?: DateRangeType | null;
+  /**
+   * Начальный промежуток при монтировании.
+   */
+  defaultValue?: DateRangeType | null;
+  /**
+   * Запрещает выбор даты в прошлом.
+   * Применяется, если не заданы `shouldDisableDate` и `disableFuture`.
+   */
   disablePast?: boolean;
+  /**
+   * Запрещает выбор даты в будущем.
+   * Применяется, если не задано `shouldDisableDate`.
+   */
   disableFuture?: boolean;
+  /**
+   * Отключает селекторы выбора месяца/года.
+   */
   disablePickers?: boolean;
+  /**
+   * `aria-label` для изменения дня.
+   */
   changeDayLabel?: string;
+  /**
+   * День недели, с которого начинается неделя.
+   */
   weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
-  onChange?: (value: DateRangeType | undefined) => void;
+  /**
+   * Обработчик изменения выбранного промежутка.
+   */
+  onChange?: (value: DateRangeType | undefined) => void; // TODO [>=8]: поменять тип на `(value?: DateRangeType | null) => void`
+  /**
+   * Функция для проверки запрета выбора даты.
+   */
   shouldDisableDate?: (value: Date) => boolean;
+  /**
+   * @deprecated Свойство не используется.
+   */
   onClose?: () => void;
 }
 
-const getIsDaySelected = (day: Date, value?: DateRangeType) => {
+const getIsDaySelected = (day: Date, value?: DateRangeType | null) => {
   if (!value?.[0] || !value[1]) {
     return false;
   }
@@ -85,7 +118,6 @@ export const CalendarRange = ({
   disablePast,
   disableFuture,
   shouldDisableDate,
-  onClose,
   weekStartsOn = 1,
   disablePickers,
   prevMonthLabel = 'Предыдущий месяц',
@@ -103,10 +135,15 @@ export const CalendarRange = ({
   getRootRef,
   ...props
 }: CalendarRangeProps): React.ReactNode => {
-  const [value, updateValue] = useCustomEnsuredControl<DateRangeType | undefined>({
+  const _onChange = React.useCallback(
+    (newValue: DateRangeType | null | undefined) => onChange?.(newValue || undefined),
+    [onChange],
+  );
+
+  const [value, updateValue] = useCustomEnsuredControl<DateRangeType | null | undefined>({
     value: valueProp,
     defaultValue,
-    onChange,
+    onChange: _onChange,
   });
 
   const {
@@ -128,20 +165,37 @@ export const CalendarRange = ({
 
   const handleKeyDown = React.useCallback(
     (event: React.KeyboardEvent) => {
-      if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(event.key)) {
+      if (
+        [
+          'ArrowUp',
+          'ArrowDown',
+          'ArrowLeft',
+          'ArrowRight',
+          'Home',
+          'End',
+          'PageUp',
+          'PageDown',
+        ].includes(event.key)
+      ) {
         event.preventDefault();
-      }
 
-      const newFocusedDay = navigateDate(focusedDay ?? value?.[1], event.key);
+        const newFocusedDay = navigateDate(focusedDay ?? value?.[1], event.key);
 
-      if (
-        newFocusedDay &&
-        !isSameMonth(newFocusedDay, viewDate) &&
-        !isSameMonth(newFocusedDay, addMonths(viewDate, 1))
-      ) {
-        setViewDate(newFocusedDay);
+        if (
+          newFocusedDay &&
+          !isSameMonth(newFocusedDay, viewDate) &&
+          !isSameMonth(newFocusedDay, addMonths(viewDate, 1))
+        ) {
+          setViewDate(newFocusedDay);
+        }
+        setFocusedDay(newFocusedDay);
+        return;
+      }
+
+      if ((event.key === 'Enter' || event.key === ' ') && isHTMLElement(event.target)) {
+        event.preventDefault();
+        event.target.click?.();
       }
-      setFocusedDay(newFocusedDay);
     },
     [focusedDay, setFocusedDay, setViewDate, value, viewDate],
   );

package/src/components/CalendarTime/CalendarTime.module.css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["./CalendarTime.module.css"],"names":["host","host__withoutDone","picker","divider","button"],"mappings":"AAAA;AAAA,E,aAAAA,M,WAAA;AAAA,E,aAKAC,mB,WALA;AAAA,E,aASAC,Q,WATA;AAAA,E,aAaAC,S,WAbA;AAAA,E,aAmBAC,Q,WAnBA;AAAA;AAAA","file":"CalendarTime.module.css.d.ts","sourceRoot":""}