add status a11y message to scheduler (DevExpress#29303)

Co-authored-by: Vladimir Bushmanov <[email protected]>

Author: Ambrozy

e2e/testcafe-devextreme/tests/scheduler/common/a11y/scheduler.ts

@@ -8,22 +8,18 @@ import { checkOptions } from './axe_options';
 fixture.disablePageReloads`a11y - appointment`
   .page(url(__dirname, '../../../container.html'));
 
-test('Scheduler should have right aria attributes', async (t) => {
+test('Scheduler should have right aria attributes after view changed', async (t) => {
   const scheduler = new Scheduler('#container');
 
-  await t.expect(
-    scheduler.element.getAttribute('aria-label'),
-  ).eql('Scheduler. Month view');
+  await t.expect(scheduler.element.getAttribute('aria-label')).contains('Scheduler. Month view');
+  await t.expect(scheduler.getGeneralStatusContainer().textContent).contains('Scheduler. Month view');
 
-  await t.expect(
-    scheduler.element.getAttribute('role'),
-  ).eql('group');
+  await t.expect(scheduler.element.getAttribute('role')).eql('group');
 
   await scheduler.option('currentView', 'week');
 
-  await t.expect(
-    scheduler.element.getAttribute('aria-label'),
-  ).eql('Scheduler. Week view');
+  await t.expect(scheduler.element.getAttribute('aria-label')).contains('Scheduler. Week view');
+  await t.expect(scheduler.getGeneralStatusContainer().textContent).contains('Scheduler. Week view');
 
   await a11yCheck(t, checkOptions, '#container');
 }).before(async () => {

e2e/testcafe-devextreme/tests/scheduler/common/a11y/status.ts

@@ -0,0 +1,120 @@
+import Scheduler from 'devextreme-testcafe-models/scheduler';
+import { createWidget } from '../../../../helpers/createWidget';
+import url from '../../../../helpers/getPageUrl';
+
+fixture.disablePageReloads`a11y - appointment`
+  .page(url(__dirname, '../../../container.html'));
+
+const today = '2025-04-30T15:00:00.000Z';
+const appointments = [
+  {
+    startDate: '2025-04-25T21:30:00.000Z',
+    endDate: '2025-04-25T23:30:00.000Z',
+    recurrenceRule: 'FREQ=HOURLY;INTERVAL=15;COUNT=15',
+  }, {
+    startDate: '2025-04-30T15:00:00.000Z',
+    endDate: '2025-04-30T16:00:00.000Z',
+  }, {
+    startDate: '2025-04-26T00:30:00.000Z',
+    endDate: '2025-04-26T02:30:00.000Z',
+    recurrenceRule: 'FREQ=HOURLY;INTERVAL=15;COUNT=15',
+  }, {
+    startDate: '2025-05-02T15:00:00.000Z',
+    endDate: '2025-05-02T16:00:00.000Z',
+  },
+];
+
+const statusCheck = async (t: TestController, scheduler: Scheduler, status: string) => {
+  await t.expect(scheduler.element.getAttribute('aria-label')).contains(status);
+  await t.expect(scheduler.getGeneralStatusContainer().textContent).contains(status);
+};
+const statusCheckEql = async (t: TestController, scheduler: Scheduler, status: string) => {
+  await t.expect(scheduler.element.getAttribute('aria-label')).match(new RegExp(status));
+  await t.expect(scheduler.getGeneralStatusContainer().textContent).match(new RegExp(status));
+};
+
+const options = [
+  ['agenda', 'Agenda view: from April 30, 2025 to May 6, 2025', [0, 9, 19]],
+  ['day', 'Day view: April 30, 2025', [0, 3, 5]],
+  ['month', 'Month view: from March 2025 to May 2025', [0, 17, 35]],
+  ['timelineDay', 'Timeline Day view: April 30, 2025', [0, 3, 5]],
+  ['timelineMonth', 'Timeline Month view: April 2025', [0, 11, 21]],
+  ['timelineWeek', 'Timeline Week view: from April 27, 2025 to May 3, 2025', [0, 12, 25]],
+  ['timelineWorkWeek', 'Timeline Work Week view: from April 28, 2025 to May 2, 2025', [0, 9, 18]],
+  ['week', 'Week view: from April 27, 2025 to May 3, 2025', [0, 13, 27]],
+  ['workWeek', 'Work Week view: from April 28, 2025 to May 2, 2025', [0, 10, 20]],
+  ['Two Weeks', 'Two Weeks view: from April 27, 2025 to May 10, 2025', [0, 14, 29]],
+] as const;
+const indicatorOnView = 'The current time indicator is visible in the view';
+const indicatorNotOnView = 'The current time indicator is not visible on the screen';
+
+options.forEach(([currentView, title, counts]) => {
+  counts.forEach((appointmentsCount, index) => {
+    const schedulerConfig = {
+      timeZone: 'America/Los_Angeles',
+      dataSource: appointments.slice(0, 2 * index),
+      views: [
+        'agenda', 'day', 'month', 'timelineDay', 'timelineMonth', 'timelineWeek', 'timelineWorkWeek', 'week', 'workWeek', {
+          name: 'Two Weeks',
+          type: 'week',
+          intervalCount: 2,
+        },
+      ],
+      currentView,
+      indicatorTime: today,
+      currentDate: today,
+    };
+    // TODO(2): use `appointmentsCount` here
+    const generalStatus = `Scheduler. ${title} with ${index === 0 ? 0 : '\\d*'} appointments`;
+
+    test(`Scheduler should have correct status message [view=${currentView}, count=${appointmentsCount}, indicator=false]`, async (t) => {
+      const scheduler = new Scheduler('#container');
+
+      await statusCheckEql(t, scheduler, generalStatus);
+    }).before(async () => {
+      await createWidget('dxScheduler', { ...schedulerConfig, showCurrentTimeIndicator: false });
+    });
+
+    test(`Scheduler should have correct status message [view=${currentView}, count=${appointmentsCount}, indicator=true]`, async (t) => {
+      const scheduler = new Scheduler('#container');
+
+      await t.click(scheduler.toolbar.navigator.nextButton);
+      await statusCheck(t, scheduler, currentView === 'month' ? indicatorOnView : indicatorNotOnView);
+
+      await t.click(scheduler.toolbar.navigator.prevButton);
+      await statusCheckEql(t, scheduler, `${generalStatus}. ${indicatorOnView}`);
+
+      await t.click(scheduler.toolbar.navigator.prevButton);
+      await statusCheck(t, scheduler, indicatorNotOnView);
+    }).before(async () => {
+      await createWidget('dxScheduler', { ...schedulerConfig, showCurrentTimeIndicator: true });
+    });
+  });
+});
+
+[
+  ['timelineWeek', 'Scheduler. Timeline Week view: from April 27, 2025 to May 3, 2025 with 5 appointments'],
+  ['week', 'Scheduler. Week view: from April 27, 2025 to May 3, 2025 with 5 appointments'],
+].forEach(([currentView, title]) => {
+  test(`Scheduler should have correct status message if the appointments are partial [view=${currentView}]`, async (t) => {
+    const scheduler = new Scheduler('#container');
+
+    await statusCheckEql(t, scheduler, title);
+  }).before(async () => {
+    await createWidget('dxScheduler', {
+      timeZone: 'America/Los_Angeles',
+      dataSource: [{
+        startDate: '2025-04-29T23:18:00.000Z',
+        endDate: '2025-04-30T16:12:00.000Z',
+      }, {
+        startDate: '2025-04-26T23:18:00.000Z',
+        endDate: '2025-04-27T12:12:00.000Z',
+        recurrenceRule: 'FREQ=DAILY;INTERVAL=2;COUNT=5',
+      }],
+      views: ['timelineWeek', 'week'],
+      currentView,
+      indicatorTime: today,
+      currentDate: today,
+    });
+  });
+});

packages/devextreme-scss/scss/widgets/base/scheduler/_common.scss

@@ -7,6 +7,15 @@ $scheduler-appointment-collector-margin: 3px;
 $scheduler-appointment-collector-height: 20px;
 $scheduler-popup-scrollable-content-padding: 20px;
 
+// NOTE: a11y aria-live container must be visible to allow screen readers read it
+.dx-scheduler-a11y-status-container {
+  position: fixed;
+  left: 0;
+  top: 0;
+  clip: rect(1px, 1px, 1px, 1px);
+  clip-path: polygon(0 0);
+}
+
 .dx-scheduler-appointment-popup {
   .dx-popup-content {
     padding-top: 0;

packages/devextreme/js/__internal/core/utils/m_type.ts

@@ -28,7 +28,7 @@ const isDate = function (object) {
   return type(object) === 'date';
 };
 
-const isDefined = function (object) {
+const isDefined = function <T>(object: T | null | undefined): object is T {
   return (object !== null) && (object !== undefined);
 };
 

packages/devextreme/js/__internal/scheduler/a11y_status/a11y_status_render.ts

@@ -0,0 +1,11 @@
+import type { dxElementWrapper } from '@js/core/renderer';
+import $ from '@js/core/renderer';
+
+const CLASSES = {
+  container: 'dx-scheduler-a11y-status-container',
+};
+
+export const createA11yStatusContainer = (statusText = ''): dxElementWrapper => $('<div>')
+  .text(statusText)
+  .addClass(CLASSES.container)
+  .attr('role', 'status');

packages/devextreme/js/__internal/scheduler/a11y_status/a11y_status_text.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { getA11yStatusText } from './a11y_status_text';
+
+describe('getA11yStatusText', () => {
+  it('should return text custom view', () => {
+    expect(getA11yStatusText(
+      {
+        name: 'Two Weeks',
+        type: 'week',
+        intervalCount: 2,
+      },
+      new Date(2021, 10, 17, 1),
+      new Date(2021, 10, 27, 12),
+      20,
+    )).toEqual('Scheduler. Two Weeks view: from November 17, 2021 to November 27, 2021 with 20 appointments');
+  });
+
+  it('should return text month view', () => {
+    expect(getA11yStatusText(
+      'month',
+      new Date(2021, 9, 27, 1),
+      new Date(2021, 11, 3, 12),
+      20,
+    )).toEqual('Scheduler. Month view: from October 2021 to December 2021 with 20 appointments');
+  });
+
+  it('should return text week view', () => {
+    expect(getA11yStatusText(
+      'week',
+      new Date(2021, 10, 21, 1),
+      new Date(2021, 10, 27, 12),
+      20,
+    )).toEqual('Scheduler. Week view: from November 21, 2021 to November 27, 2021 with 20 appointments');
+  });
+
+  it('should return text day view', () => {
+    expect(getA11yStatusText(
+      'day',
+      new Date(2021, 10, 24, 1),
+      new Date(2021, 10, 24, 12),
+      20,
+    )).toEqual('Scheduler. Day view: November 24, 2021 with 20 appointments');
+  });
+
+  it('should return text with indicator on the view', () => {
+    expect(getA11yStatusText(
+      'day',
+      new Date(2021, 10, 24, 1),
+      new Date(2021, 10, 24, 12),
+      20,
+      new Date(2021, 10, 24, 10),
+    )).toEqual('Scheduler. Day view: November 24, 2021 with 20 appointments. The current time indicator is visible in the view');
+  });
+
+  it('should return text with indicator out of the view', () => {
+    expect(getA11yStatusText(
+      'day',
+      new Date(2021, 10, 24, 1),
+      new Date(2021, 10, 24, 12),
+      20,
+      new Date(2021, 10, 12, 10),
+    )).toEqual('Scheduler. Day view: November 24, 2021 with 20 appointments. The current time indicator is not visible on the screen');
+  });
+});

packages/devextreme/js/__internal/scheduler/a11y_status/a11y_status_text.ts

@@ -0,0 +1,78 @@
+import dateLocalization from '@js/common/core/localization/date';
+import messageLocalization from '@js/common/core/localization/message';
+import { isObject } from '@js/core/utils/type';
+import type { ViewType } from '@js/ui/scheduler';
+
+import type { RawViewType } from '../header/types';
+
+const KEYS = {
+  dateRange: 'dxScheduler-dateRange',
+  label: 'dxScheduler-ariaLabel',
+  indicatorPresent: 'dxScheduler-ariaLabel-currentIndicator-present',
+  indicatorNotPresent: 'dxScheduler-ariaLabel-currentIndicator-not-present',
+};
+const viewTypeLocalization: Record<ViewType, string> = {
+  agenda: 'dxScheduler-switcherAgenda',
+  day: 'dxScheduler-switcherDay',
+  month: 'dxScheduler-switcherMonth',
+  week: 'dxScheduler-switcherWeek',
+  workWeek: 'dxScheduler-switcherWorkWeek',
+  timelineDay: 'dxScheduler-switcherTimelineDay',
+  timelineMonth: 'dxScheduler-switcherTimelineMonth',
+  timelineWeek: 'dxScheduler-switcherTimelineWeek',
+  timelineWorkWeek: 'dxScheduler-switcherTimelineWorkWeek',
+};
+
+const localizeMonth = (date: Date): string => String(dateLocalization.format(date, 'monthAndYear'));
+const localizeDate = (date: Date): string => `${dateLocalization.format(date, 'monthAndDay')}, ${dateLocalization.format(date, 'year')}`;
+const localizeCurrentIndicator = (
+  date: Date,
+  startDate: Date,
+  endDate: Date,
+): string => messageLocalization.format(
+  date >= startDate && date < endDate
+    ? KEYS.indicatorPresent
+    : KEYS.indicatorNotPresent,
+);
+const localizeName = (viewName?: string, viewType?: string): string => {
+  if (viewName) {
+    return viewName;
+  }
+  if (viewType) {
+    return messageLocalization.format(viewTypeLocalization[viewType]);
+  }
+
+  return '';
+};
+
+export const getA11yStatusText = (
+  view: RawViewType,
+  startDate: Date,
+  endDate: Date,
+  appointmentCount: number,
+  indicatorTime?: Date,
+): string => {
+  const viewType = isObject(view) ? view.type : view;
+  const viewName = isObject(view) ? view.name : undefined;
+  const viewTypeLabel = localizeName(viewName, viewType);
+
+  const isMonth = viewType === 'month' || viewType === 'timelineMonth';
+  const startDateText = isMonth ? localizeMonth(startDate) : localizeDate(startDate);
+  const endDateText = isMonth ? localizeMonth(endDate) : localizeDate(endDate);
+  const intervalText = startDateText === endDateText
+    ? `${startDateText}`
+    // @ts-expect-error ts-error
+    : messageLocalization.format(KEYS.dateRange, startDateText, endDateText);
+
+  const statusText = messageLocalization
+    // @ts-expect-error
+    .format(KEYS.label, viewTypeLabel, intervalText, appointmentCount);
+
+  if (indicatorTime) {
+    const indicatorStatus = localizeCurrentIndicator(indicatorTime, startDate, endDate);
+
+    return `${statusText}. ${indicatorStatus}`;
+  }
+
+  return statusText;
+};

packages/devextreme/js/__internal/scheduler/appointments/m_appointment_collection.ts

@@ -36,6 +36,7 @@ import { getAppointmentTakesSeveralDays, sortAppointmentsByStartDate } from './d
 import { AgendaAppointment, Appointment } from './m_appointment';
 import { createAgendaAppointmentLayout, createAppointmentLayout } from './m_appointment_layout';
 import { getAppointmentDateRange } from './resizing/m_core';
+import { countVisibleAppointments } from './utils/countVisibleAppointments';
 
 const COMPONENT_CLASS = 'dx-scheduler-scrollable-appointments';
 
@@ -70,6 +71,10 @@ class SchedulerAppointments extends CollectionWidget {
     return this.option('getAppointmentDataProvider')();
   }
 
+  get appointmentsCount(): number {
+    return countVisibleAppointments(this.option('items') ?? []);
+  }
+
   constructor(element, options) {
     super(element, options);
     this._virtualAppointments = {};

packages/devextreme/js/__internal/scheduler/appointments/m_text_utils.ts

@@ -24,7 +24,6 @@ export const getFormatType = (startDate, endDate, isAllDay, isDateAndTimeView?)
   return 'DATETIME';
 };
 
-// @ts-expect-error
 export const formatDates = (startDate, endDate, formatType) => {
   const dateFormat = 'monthandday';
   const timeFormat = 'shorttime';
@@ -45,6 +44,6 @@ export const formatDates = (startDate, endDate, formatType) => {
     case 'DATE':
       return `${dateLocalization.format(startDate, dateFormat)}${isSameDate ? '' : ` - ${dateLocalization.format(endDate, dateFormat)}`}`;
     default:
-      break;
+      return undefined;
   }
 };