PivotGrid A11y and KBN - The expand icons are not accessible via keyboard (KBN) (#33709)

Author: aleksei-semikozov

e2e/testcafe-devextreme/tests/common/pivotGrid/kbn/etalons/pivotgrid_kbn_expandable_cell_focused (fluent.blue.light).png

@@ -0,0 +1,62 @@
+import { createScreenshotsComparer } from 'devextreme-screenshot-comparer';
+import PivotGrid from 'devextreme-testcafe-models/pivotGrid';
+import { Selector } from 'testcafe';
+import { createWidget } from '../../../../helpers/createWidget';
+import url from '../../../../helpers/getPageUrl';
+import { testScreenshot } from '../../../../helpers/themeUtils';
+import { sales } from '../data';
+
+fixture.disablePageReloads`pivotGrid_kbn_expandIcon`
+  .page(url(__dirname, '../../../container.html'));
+
+const PIVOT_GRID_SELECTOR = '#container';
+
+test('Expandable cell should have a visible focus outline when focused by keyboard', async (t) => {
+  const { takeScreenshot, compareResults } = createScreenshotsComparer(t);
+  const pivotGrid = new PivotGrid(PIVOT_GRID_SELECTOR);
+
+  // Tab through the grid until an expandable cell is focused by keyboard
+  // so that the :focus-visible outline is applied.
+  for (let i = 0; i < 10; i += 1) {
+    await t.pressKey('tab');
+
+    if (await Selector(':focus').hasAttribute('aria-expanded')) {
+      break;
+    }
+  }
+
+  await t
+    .expect(Selector(':focus').hasAttribute('aria-expanded'))
+    .ok('an expandable cell is focused');
+
+  await testScreenshot(t, takeScreenshot, 'pivotgrid_kbn_expandable_cell_focused.png', { element: pivotGrid.element });
+
+  await t
+    .expect(compareResults.isValid())
+    .ok(compareResults.errorMessages());
+}).before(async () => createWidget('dxPivotGrid', {
+  width: 600,
+  allowExpandAll: true,
+  fieldChooser: {
+    enabled: false,
+  },
+  dataSource: {
+    fields: [{
+      dataField: 'region',
+      area: 'row',
+      expanded: false,
+    }, {
+      dataField: 'city',
+      area: 'row',
+    }, {
+      dataField: 'date',
+      area: 'column',
+    }, {
+      dataField: 'amount',
+      area: 'data',
+      summaryType: 'sum',
+      dataType: 'number',
+    }],
+    store: sales,
+  },
+}));

e2e/testcafe-devextreme/tests/common/pivotGrid/kbn/expandIcon.ts

@@ -127,6 +127,16 @@ $pivotgrid-expand-icon-text-offset: 0;
 }
 
 .dx-pivotgrid {
+  td:has(> .dx-expand-icon-container:focus-visible) {
+    outline: 2px solid;
+    outline-color: $pivotgrid-accent-color;
+    outline-offset: -2px;
+  }
+
+  .dx-expand-icon-container:focus-visible {
+    outline: none;
+  }
+
   .dx-column-header,
   .dx-filter-header {
     .dx-pivotgrid-toolbar {

packages/devextreme-scss/scss/widgets/base/pivotGrid/_index.scss

@@ -198,6 +198,11 @@ abstract class AreaItem {
             span.classList.add(PIVOTGRID_EXPAND_CLASS);
             div.appendChild(span);
             td.appendChild(div);
+            const ariaLabel = String(cell.text ?? cell.value ?? '');
+            div.setAttribute('role', 'button');
+            div.setAttribute('aria-label', encodeHtml ? ariaLabel : $('<div>').html(ariaLabel).text());
+            div.setAttribute('aria-expanded', String(cell.expanded));
+            div.setAttribute('tabindex', '0');
           }
 
           cellText = this._getCellText(cell, encodeHtml);

packages/devextreme/js/__internal/grids/pivot_grid/area_item/m_area_item.ts

@@ -21,6 +21,7 @@ import type { ButtonStyle, Properties } from '@js/ui/button';
 import Button from '@js/ui/button';
 import ContextMenu from '@js/ui/context_menu';
 import Popup from '@js/ui/popup/ui.popup';
+import { restoreFocus, saveFocusedElementInfo } from '@js/ui/shared/accessibility';
 import { current, isGeneric } from '@js/ui/themes';
 import Widget from '@ts/core/widget/widget';
 import gridCoreUtils from '@ts/grids/grid_core/m_utils';
@@ -890,6 +891,35 @@ class PivotGrid extends Widget {
     });
   }
 
+  _handleCellKeyDown(e) {
+    if (e.repeat) {
+      return;
+    }
+    if (e.key !== 'Enter' && e.key !== ' ') {
+      return;
+    }
+    const args = this._createEventArgs(e.currentTarget, e);
+    const { cell } = args;
+    if (!cell || !isDefined(cell.expanded)) {
+      return;
+    }
+    e.preventDefault();
+    this._trigger('onCellClick', args);
+    if (args.cancel) {
+      return;
+    }
+    const $control = $(e.currentTarget).find('.dx-expand-icon-container');
+    saveFocusedElementInfo($control.get(0), this);
+    const onReady = () => {
+      this.off('contentReady', onReady);
+      restoreFocus(this);
+    };
+    this.on('contentReady', onReady);
+    setTimeout(() => {
+      this._dataController[cell.expanded ? 'collapseHeaderItem' : 'expandHeaderItem'](args.area, cell.path);
+    });
+  }
+
   _getNoDataText() {
     return this.option('texts.noData');
   }
@@ -1089,6 +1119,7 @@ class PivotGrid extends Widget {
       .toggleClass('dx-word-wrap', !!that.option('wordWrapEnabled'));
 
     eventsEngine.on($table, addNamespace(clickEventName, 'dxPivotGrid'), 'td', that._handleCellClick.bind(that));
+    eventsEngine.on($table, addNamespace('keydown', 'dxPivotGrid'), 'td', that._handleCellKeyDown.bind(that));
 
     return $table;
   }

packages/devextreme/js/__internal/grids/pivot_grid/m_widget.ts

@@ -55,7 +55,7 @@ export type PivotGridTotalDisplayMode = 'both' | 'columns' | 'none' | 'rows';
  * @type object
  * @inherits Cancelable,NativeEventInfo
  */
-export type CellClickEvent = Cancelable & NativeEventInfo<dxPivotGrid, MouseEvent | PointerEvent> & {
+export type CellClickEvent = Cancelable & NativeEventInfo<dxPivotGrid, KeyboardEvent | MouseEvent | PointerEvent> & {
     /** @docid _ui_pivot_grid_CellClickEvent.area */
     readonly area?: string;
     /** @docid _ui_pivot_grid_CellClickEvent.cellElement */

packages/devextreme/js/ui/pivot_grid.d.ts

@@ -85,5 +85,109 @@ QUnit.module('PivotGrid markup tests', () => {
         clock.restore();
     });
 
+    const createExpandableDataSource = () => ({
+        fields: [
+            { dataField: 'region', area: 'row' },
+            { dataField: 'city', area: 'row' },
+            { dataField: 'year', area: 'column', expanded: true },
+            { dataField: 'quarter', area: 'column' },
+            { dataField: 'amount', area: 'data', summaryType: 'sum', dataType: 'number' }
+        ],
+        store: [
+            { region: 'N', city: 'B', year: 2020, quarter: 'Q1', amount: 100 },
+            { region: 'N', city: 'NY', year: 2020, quarter: 'Q2', amount: 200 },
+            { region: 'S', city: 'M', year: 2021, quarter: 'Q1', amount: 300 }
+        ]
+    });
+
+    QUnit.test('Expand control has aria-expanded reflecting expanded state', function(assert) {
+        if(!windowUtils.hasWindow()) {
+            assert.ok(true, 'skipped on serverSide');
+            return;
+        }
+        const clock = sinon.useFakeTimers();
+        try {
+            const pivotGrid = createPivotGrid({ dataSource: createExpandableDataSource() });
+            clock.tick(10);
+
+            const $expandedControl = pivotGrid.$element().find('.dx-pivotgrid-expanded').first().find('.dx-expand-icon-container');
+            const $collapsedControl = pivotGrid.$element().find('.dx-pivotgrid-collapsed').first().find('.dx-expand-icon-container');
+
+            assert.ok($expandedControl.length > 0, 'expanded control present');
+            assert.ok($collapsedControl.length > 0, 'collapsed control present');
+            assert.strictEqual($expandedControl.attr('aria-expanded'), 'true', 'expanded control has aria-expanded="true"');
+            assert.strictEqual($collapsedControl.attr('aria-expanded'), 'false', 'collapsed control has aria-expanded="false"');
+        } finally {
+            clock.restore();
+        }
+    });
+
+    QUnit.test('Expand control is a focusable button, td keeps native cell semantics', function(assert) {
+        if(!windowUtils.hasWindow()) {
+            assert.ok(true, 'skipped on serverSide');
+            return;
+        }
+        const clock = sinon.useFakeTimers();
+        try {
+            const pivotGrid = createPivotGrid({ dataSource: createExpandableDataSource() });
+            clock.tick(10);
+
+            const $collapsedTd = pivotGrid.$element().find('.dx-pivotgrid-collapsed').first();
+            const $collapsedControl = $collapsedTd.find('.dx-expand-icon-container');
+
+            assert.strictEqual($collapsedControl.attr('role'), 'button', 'control has role="button"');
+            assert.strictEqual($collapsedControl.attr('tabindex'), '0', 'control is focusable');
+            assert.strictEqual($collapsedTd.attr('role'), undefined, 'td keeps native cell role');
+            assert.strictEqual($collapsedTd.attr('tabindex'), undefined, 'td is not in the tab order');
+            assert.strictEqual($collapsedTd.attr('aria-expanded'), undefined, 'td has no aria-expanded');
+        } finally {
+            clock.restore();
+        }
+    });
+
+    QUnit.test('Expand control aria-label matches the displayed text, not the raw value', function(assert) {
+        if(!windowUtils.hasWindow()) {
+            assert.ok(true, 'skipped on serverSide');
+            return;
+        }
+        const clock = sinon.useFakeTimers();
+        try {
+            const dataSource = createExpandableDataSource();
+            dataSource.fields[0].customizeText = (cellInfo) => `${cellInfo.valueText} region`;
+            const pivotGrid = createPivotGrid({ dataSource });
+            clock.tick(10);
+
+            const $collapsedTd = pivotGrid.$element().find('.dx-pivotgrid-collapsed').first().closest('td');
+            const $collapsedControl = $collapsedTd.find('.dx-expand-icon-container');
+            const displayedText = $collapsedTd.text().trim();
+
+            assert.notStrictEqual($collapsedControl.attr('aria-label').indexOf(' region'), -1, 'aria-label uses customized display text');
+            assert.strictEqual($collapsedControl.attr('aria-label'), displayedText, 'aria-label equals the visible cell text');
+        } finally {
+            clock.restore();
+        }
+    });
+
+    QUnit.test('Non-expandable cell has no expand control', function(assert) {
+        if(!windowUtils.hasWindow()) {
+            assert.ok(true, 'skipped on serverSide');
+            return;
+        }
+        const clock = sinon.useFakeTimers();
+        try {
+            const pivotGrid = createPivotGrid({ dataSource: createExpandableDataSource() });
+            clock.tick(10);
+
+            const $dataCell = pivotGrid.$element().find('.dx-area-data-cell td').first();
+
+            assert.ok($dataCell.length > 0, 'data cell exists');
+            assert.strictEqual($dataCell.find('.dx-expand-icon-container').length, 0, 'no expand control in a non-expandable cell');
+            assert.strictEqual($dataCell.attr('role'), undefined, 'data cell has no role');
+            assert.strictEqual($dataCell.attr('tabindex'), undefined, 'data cell is not focusable');
+        } finally {
+            clock.restore();
+        }
+    });
+
 });