feat: add accessibleName property to Grid (#8230)

vaadin · Nov 27, 2024 · 50c2305 · 50c2305
1 parent 89e79cb
commit 50c2305
Show file tree

Hide file tree

Showing 6 changed files with 73 additions and 3 deletions.
diff --git a/packages/grid/src/vaadin-grid-a11y-mixin.d.ts b/packages/grid/src/vaadin-grid-a11y-mixin.d.ts
@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2024 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+export declare function A11yMixin<T extends Constructor<HTMLElement>>(base: T): Constructor<A11yMixinClass> & T;
+
+export declare class A11yMixinClass {
+  /**
+   * String used to label the grid to screen reader users.
+   * @attr {string} accessible-name
+   */
+  accessibleName: string;
+}
diff --git a/packages/grid/src/vaadin-grid-a11y-mixin.js b/packages/grid/src/vaadin-grid-a11y-mixin.js
@@ -10,6 +10,17 @@ import { iterateChildren, iterateRowCells } from './vaadin-grid-helpers.js';
  */
 export const A11yMixin = (superClass) =>
   class A11yMixin extends superClass {
+    static get properties() {
+      return {
+        /**
+         * String used to label the grid to screen reader users.
+         * @attr {string} accessible-name
+         */
+        accessibleName: {
+          type: String,
+        },
+      };
+    }
     static get observers() {
       return ['_a11yUpdateGridSize(size, _columnTree)'];
     }

diff --git a/packages/grid/src/vaadin-grid-mixin.d.ts b/packages/grid/src/vaadin-grid-mixin.d.ts
@@ -5,6 +5,7 @@
  */
 import type { Constructor } from '@open-wc/dedupe-mixin';
 import type { DisabledMixinClass } from '@vaadin/a11y-base/src/disabled-mixin.js';
+import type { A11yMixinClass } from './vaadin-grid-a11y-mixin.js';
 import type { ActiveItemMixinClass } from './vaadin-grid-active-item-mixin.js';
 import type { ArrayDataProviderMixinClass } from './vaadin-grid-array-data-provider-mixin.js';
 import type { GridBodyRenderer, GridColumn, GridHeaderFooterRenderer } from './vaadin-grid-column.js';
@@ -162,7 +163,8 @@ export interface GridEventMap<TItem> extends HTMLElementEventMap, GridCustomEven
 
 export declare function GridMixin<TItem, T extends Constructor<HTMLElement>>(
   base: T,
-): Constructor<ActiveItemMixinClass<TItem>> &
+): Constructor<A11yMixinClass> &
+  Constructor<ActiveItemMixinClass<TItem>> &
   Constructor<ArrayDataProviderMixinClass<TItem>> &
   Constructor<ColumnReorderingMixinClass> &
   Constructor<DataProviderMixinClass<TItem>> &
@@ -179,6 +181,7 @@ export declare function GridMixin<TItem, T extends Constructor<HTMLElement>>(
 
 export interface GridMixinClass<TItem>
   extends DisabledMixinClass,
+    A11yMixinClass,
     ActiveItemMixinClass<TItem>,
     ArrayDataProviderMixinClass<TItem>,
     DataProviderMixinClass<TItem>,

diff --git a/packages/grid/src/vaadin-grid.js b/packages/grid/src/vaadin-grid.js
@@ -274,7 +274,7 @@ class Grid extends GridMixin(ElementMixin(ThemableMixin(ControllerMixin(PolymerE
         column-reordering-allowed$="[[columnReorderingAllowed]]"
         empty-state$="[[__emptyState]]"
       >
-        <table id="table" role="treegrid" aria-multiselectable="true" tabindex="0">
+        <table id="table" role="treegrid" aria-multiselectable="true" tabindex="0" aria-label$="[[accessibleName]]">
           <caption id="sizer" part="row"></caption>
           <thead id="header" role="rowgroup"></thead>
           <tbody id="items" role="rowgroup"></tbody>

diff --git a/packages/grid/src/vaadin-lit-grid.js b/packages/grid/src/vaadin-lit-grid.js
@@ -5,6 +5,7 @@
  */
 import './vaadin-lit-grid-column.js';
 import { html, LitElement } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import { isIOS, isSafari } from '@vaadin/component-base/src/browser-utils.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
@@ -42,7 +43,13 @@ class Grid extends GridMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)
         column-reordering-allowed="${this.columnReorderingAllowed}"
         ?empty-state="${this.__emptyState}"
       >
-        <table id="table" role="treegrid" aria-multiselectable="true" tabindex="0">
+        <table
+          id="table"
+          role="treegrid"
+          aria-multiselectable="true"
+          tabindex="0"
+          aria-label="${ifDefined(this.accessibleName)}"
+        >
           <caption id="sizer" part="row"></caption>
           <thead id="header" role="rowgroup"></thead>
           <tbody id="items" role="rowgroup"></tbody>

diff --git a/packages/grid/test/accessibility.common.js b/packages/grid/test/accessibility.common.js
@@ -359,4 +359,37 @@ describe('accessibility', () => {
       });
     });
   });
+
+  describe('accessibleName', () => {
+    beforeEach(() => {
+      initFixture('default');
+    });
+
+    it('should not define aria-label on the table when accessibleName is not set', async () => {
+      await nextFrame();
+      expect(grid.$.table.getAttribute('aria-label')).to.be.null;
+    });
+
+    it('should define aria-label on the table when accessibleName is set', async () => {
+      grid.accessibleName = 'Grid accessible name';
+      await nextFrame();
+      expect(grid.$.table.getAttribute('aria-label')).to.equal('Grid accessible name');
+    });
+
+    it('should update aria-label on the table when accessibleName is updated', async () => {
+      grid.accessibleName = 'Grid accessible name';
+      await nextFrame();
+      grid.accessibleName = 'Updated accessible name';
+      await nextFrame();
+      expect(grid.$.table.getAttribute('aria-label')).to.equal('Updated accessible name');
+    });
+
+    it('should remove aria-label on the table when accessibleName is removed', async () => {
+      grid.accessibleName = 'Grid accessible name';
+      await nextFrame();
+      grid.accessibleName = null;
+      await nextFrame();
+      expect(grid.$.table.getAttribute('aria-label')).to.be.null;
+    });
+  });
 });