Add ARIA props to tbody when scroll is shown

This commit introduces the ability to add ARIA properties to the tbody element when a scroll is displayed. The new tBodyScrollAria prop allows for the configuration of these labels, accepting an object with optional aria-label and aria-labelledby properties. This enhancement improves accessibility by providing descriptive information to assistive technologies when tbody has a scroll.

Author: Hector Arce De Las Heras

src/components/table/__tests__/table.test.tsx

@@ -11,6 +11,7 @@ import * as useMediaDevice from '@/hooks/useMediaDevice/useMediaDevice';
 import { renderProvider } from '@/tests/renderProvider/renderProvider.utility';
 import { windowMatchMedia } from '@/tests/windowMatchMedia';
 import { DeviceBreakpointsType, ROLES } from '@/types';
+import * as hasScrollUtils from '@/utils/scroll/hasScroll';
 
 import { Table } from '../table';
 import { FormatListHeaderPriorityType } from '../types';
@@ -378,6 +379,25 @@ const mockDividerFromHeader = {
 };
 
 describe('Table component', () => {
+  beforeAll(() => {
+    global.ResizeObserver = class ResizeObserver {
+      callback;
+      constructor(callback) {
+        this.callback = callback;
+      }
+      observe() {
+        // Call the callback
+        this.callback();
+      }
+      unobserve() {
+        // do nothing
+      }
+      disconnect() {
+        // do nothing
+      }
+    };
+  });
+
   it('Renders with a valid HTML structure', async () => {
     const { container } = renderProvider(
       <Table
@@ -577,4 +597,28 @@ describe('Table component', () => {
     expect(container).toHTMLValidate();
     expect(results).toHaveNoViolations();
   });
+
+  it('When scroll appears in the tbody, tBody surface is focusable and and labels can be added', async () => {
+    // Mock hasScrollUtils and resize observer
+    jest.spyOn(hasScrollUtils, 'hasScroll').mockImplementation(() => true);
+    const { container } = renderProvider(
+      <Table
+        aria-label={'aria table label'}
+        captionDescription={'caption description'}
+        tBodyScrollArias={{ 'aria-label': 'aria-label' }}
+        {...mockBase}
+      />
+    );
+    const results = await axe(container);
+    const tbody = screen.getByRole(ROLES.REGION, { name: 'aria-label' });
+
+    expect(tbody).toBeDefined();
+    expect(tbody).toHaveAttribute('tabindex', '0');
+    expect(container).toHTMLValidate({
+      rules: {
+        'prefer-native-element': 'off',
+      },
+    });
+    expect(results).toHaveNoViolations();
+  });
 });

src/components/table/component/table.tsx

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { Footer } from '@/components/footer';
 import { Text, TextComponentType } from '@/components/text';
 import { useId } from '@/hooks';
+import { ROLES } from '@/types';
 import { pickAriaProps } from '@/utils/aria/aria';
 
 import {
@@ -106,6 +107,10 @@ export const TableComponent = (
                   styles={props.styles.header?.[props.headerVariant]}
                 >
                   <Text
+                    align={
+                      headerValue?.config?.alignHeader?.[props.device] ||
+                      headerValue?.config?.alignHeader
+                    }
                     component={TextComponentType.SPAN}
                     customTypography={props.styles.header?.[props.headerVariant]?.typography}
                     dataTestId={`${props.dataTestId}Header${index}`}
@@ -133,7 +138,15 @@ export const TableComponent = (
             )}
           </TableRowHeaderStyled>
         </TableRowGroupHeaderStyled>
-        <TableRowGroupBodyStyled styles={props.styles}>
+        <TableRowGroupBodyStyled
+          aria-label={props.hasScroll ? props.tBodyScrollArias?.['aria-label'] : undefined}
+          aria-labelledby={
+            props.hasScroll ? props.tBodyScrollArias?.['aria-labelledby'] : undefined
+          }
+          role={props.hasScroll ? ROLES.REGION : undefined}
+          styles={props.styles}
+          tabIndex={props.hasScroll ? 0 : undefined}
+        >
           {props.values.map((value, indexValue) => {
             return (
               <TableRow

src/components/table/stories/argtypes.ts

@@ -205,6 +205,19 @@ export const argtypes = (
         category: CATEGORY_CONTROL.MODIFIERS,
       },
     },
+    tBodyScrollArias: {
+      description: 'Aria label for tbody when scroll',
+      type: { name: 'object' },
+      control: { type: 'object' },
+      table: {
+        type: {
+          summary: 'TBodyScrollAriasType',
+          detail:
+            'TBodyScrollAriasType: { ["aria-label"]?: string; ["aria-labelledby"]?: string; }',
+        },
+        category: CATEGORY_CONTROL.ACCESIBILITY,
+      },
+    },
     formatListHeaderPriority: {
       description: 'When format list format, allows to select the list direction (from the table)',
       type: { name: 'string' },

src/components/table/stories/table.stories.tsx

@@ -40,6 +40,7 @@ export const Table: Story = {
     ['aria-label']: 'ariaLabel table',
     formatListInMobile: true,
     formatSideBySideInList: true,
+    tBodyScrollArias: { 'aria-label': 'ariaLabel tBody when scroll' },
     themeArgs: themesObject[themeSelected][STYLES_NAME.TABLE],
     ...mockTableWithLineSeparatorAndCenterFooter,
   },
@@ -53,6 +54,7 @@ export const TableWithDivider: Story = {
     )[0] as string,
     captionDescription: 'Table caption',
     ['aria-label']: 'ariaLabel table',
+    tBodyScrollArias: { 'aria-label': 'ariaLabel tBody when scroll' },
     themeArgs: themesObject[themeSelected][STYLES_NAME.TABLE],
     ...mockTableWithDivider,
   },
@@ -66,6 +68,7 @@ export const TableBasic: Story = {
     )[0] as string,
     captionDescription: 'Table caption',
     ['aria-label']: 'ariaLabel table',
+    tBodyScrollArias: { 'aria-label': 'ariaLabel tBody when scroll' },
     themeArgs: themesObject[themeSelected][STYLES_NAME.TABLE],
     ...mockBasicTable,
   },
@@ -78,6 +81,7 @@ export const TableCustomizable: Story = {
     ['aria-label']: 'ariaLabel table',
     lineSeparatorTopOnHeader: true,
     lineSeparatorBottomOnHeader: true,
+    tBodyScrollArias: { 'aria-label': 'ariaLabel tBody when scroll' },
     themeArgs: themesObject[themeSelected][STYLES_NAME.TABLE],
     ...mockCustomizableTable,
   },
@@ -93,6 +97,7 @@ export const TableWithCtv: Story = {
     ['aria-label']: 'ariaLabel table',
     formatListInMobile: true,
     formatSideBySideInList: true,
+    tBodyScrollArias: { 'aria-label': 'ariaLabel tBody when scroll' },
     ...mockTableWithLineSeparatorAndCenterFooter,
     ctv: {
       table: {

src/components/table/table.tsx

@@ -1,9 +1,10 @@
-import React from 'react';
+import React, { useImperativeHandle } from 'react';
 
 import { LineSeparatorLinePropsStylesType } from '@/components/lineSeparator';
 import { useMediaDevice } from '@/hooks';
 import { useStyles } from '@/hooks/useStyles/useStyles';
 import { ErrorBoundary, FallbackComponent } from '@/provider/errorBoundary';
+import { hasScroll as checkHasScroll } from '@/utils';
 
 import { TableStandAlone } from './tableStandAlone';
 import { ITable, ITableStandAlone, TableRowHeaderTypes } from './types';
@@ -27,27 +28,47 @@ const TableComponent = React.forwardRef(
     );
     const device = useMediaDevice();
 
+    const innerRef = React.useRef<HTMLTableElement>(null);
+    useImperativeHandle(ref, () => innerRef.current as HTMLTableElement, []);
+
     // Indicates if there is scrolling behind the table body to add shadow to column headers.
     const [scrollPosition, setScrollPosition] = React.useState(0);
-    const refTableBody = React.useRef<HTMLTableSectionElement>(null);
-
     React.useEffect(() => {
+      const tBody = innerRef.current?.querySelector('tbody');
       const updatePosition = () => {
-        setScrollPosition(refTableBody?.current?.scrollTop ?? 0);
+        setScrollPosition(tBody?.scrollTop ?? 0);
       };
+      tBody?.addEventListener('scroll', updatePosition);
+      return () => tBody?.removeEventListener('scroll', updatePosition);
+    }, []);
 
-      refTableBody?.current?.addEventListener('scroll', updatePosition);
-
-      return () => refTableBody?.current?.removeEventListener('scroll', updatePosition);
+    // Indicates if tBody has scroll in order to add accesibility aria props
+    const [hasScroll, setHasScroll] = React.useState(false);
+    React.useEffect(() => {
+      const tBody = innerRef.current?.querySelector('tbody');
+      let resizeObserver: ResizeObserver;
+      if (tBody) {
+        const handleTBodyResize = (tBody: HTMLTableSectionElement) => {
+          setHasScroll(checkHasScroll(tBody));
+        };
+        handleTBodyResize(tBody);
+        resizeObserver = new ResizeObserver(() => {
+          handleTBodyResize(tBody);
+        });
+        resizeObserver.observe(tBody);
+      }
+      return () => {
+        resizeObserver?.disconnect();
+      };
     }, []);
 
     return (
       <TableStandAlone
         {...props}
-        ref={ref}
+        ref={innerRef}
         device={device}
+        hasScroll={hasScroll}
         lineSeparatorLineStyles={lineSeparatorLineStyles}
-        refTableBody={refTableBody}
         scrolling={scrollPosition > 0}
         styles={styles}
       />

src/components/table/types/table.ts

@@ -150,14 +150,18 @@ type TableAriaAttributes = Pick<
   'aria-label' | 'aria-labelledby' | 'aria-describedby'
 >;
 
+type TBodyScrollAriasType = {
+  ['aria-label']?: string;
+  ['aria-labelledby']?: string;
+};
+
 /**
  * @description
  * Table props
  * @interface ITableStandAlone
  */
 export interface ITableStandAlone extends TableAriaAttributes {
   styles: TableRowHeaderTypes<string, string>;
-  refTableBody?: React.Ref<HTMLTableSectionElement>;
   lineSeparatorLineStyles: LineSeparatorLinePropsStylesType;
   lineSeparatorTopOnHeader?: boolean;
   lineSeparatorBottomOnHeader?: boolean;
@@ -173,6 +177,8 @@ export interface ITableStandAlone extends TableAriaAttributes {
   hiddenHeaderOn?: HiddenType;
   device: DeviceBreakpointsType;
   scrolling: boolean;
+  hasScroll: boolean;
+  tBodyScrollArias?: TBodyScrollAriasType;
   headerVariant?: string;
   expandedContentHelpMessage?: string;
   formatList?: { [key in DeviceBreakpointsType]?: boolean };
@@ -195,7 +201,7 @@ export interface ITableStandAlone extends TableAriaAttributes {
 export interface ITable<V = undefined extends string ? unknown : string>
   extends Omit<
       ITableStandAlone,
-      'styles' | 'lineSeparatorLineStyles' | 'device' | 'scrolling' | 'refTableBody'
+      'styles' | 'lineSeparatorLineStyles' | 'device' | 'scrolling' | 'hasScroll'
     >,
     Omit<CustomTokenTypes<TableRowHeaderTypes<string, string>>, 'cts' | 'extraCt'> {
   variant: V;

src/utils/index.ts

@@ -39,3 +39,4 @@ export * from './buildPropsDecorativeElement/buildPropsDecorativeElement';
 export * from './syntheticComponents';
 export * from './aria/aria';
 export * from './structuredClone';
+export * from './scroll';

src/utils/scroll/__tests__/hasScroll.test.ts

@@ -0,0 +1,82 @@
+import { hasHorizontalScroll, hasScroll, hasVerticalScroll } from '../hasScroll';
+
+describe('Scroll detection functions', () => {
+  let element: HTMLElement;
+
+  beforeEach(() => {
+    // Create a new element for each test
+    element = document.createElement('div');
+    document.body.appendChild(element);
+  });
+
+  afterEach(() => {
+    // Clean up the element after each test
+    document.body.removeChild(element);
+  });
+
+  it('hasVerticalScroll returns true when an element has a vertical scroll', () => {
+    Object.defineProperty(element, 'scrollHeight', {
+      value: 200,
+    });
+    Object.defineProperty(element, 'clientHeight', {
+      value: 100,
+    });
+
+    expect(hasVerticalScroll(element)).toBe(true);
+  });
+
+  it('hasVerticalScroll returns false when an element does not have a vertical scroll', () => {
+    Object.defineProperty(element, 'scrollHeight', {
+      value: 50,
+    });
+    Object.defineProperty(element, 'clientHeight', {
+      value: 100,
+    });
+
+    expect(hasVerticalScroll(element)).toBe(false);
+  });
+
+  it('hasHorizontalScroll returns true when an element has a horizontal scroll', () => {
+    Object.defineProperty(element, 'scrollWidth', {
+      value: 200,
+    });
+    Object.defineProperty(element, 'clientWidth', {
+      value: 100,
+    });
+
+    expect(hasHorizontalScroll(element)).toBe(true);
+  });
+
+  it('hasHorizontalScroll returns false when an element does not have a horizontal scroll', () => {
+    Object.defineProperty(element, 'scrollWidth', {
+      value: 50,
+    });
+    Object.defineProperty(element, 'clientWidth', {
+      value: 100,
+    });
+
+    expect(hasHorizontalScroll(element)).toBe(false);
+  });
+
+  it('hasScroll returns true when an element has a vertical or horizontal scroll', () => {
+    Object.defineProperty(element, 'scrollWidth', {
+      value: 200,
+    });
+    Object.defineProperty(element, 'clientWidth', {
+      value: 100,
+    });
+
+    expect(hasHorizontalScroll(element)).toBe(true);
+  });
+
+  it('hasScroll returns false when an element does not have a vertical or horizontal scroll', () => {
+    Object.defineProperty(element, 'scrollWidth', {
+      value: 50,
+    });
+    Object.defineProperty(element, 'clientWidth', {
+      value: 100,
+    });
+
+    expect(hasScroll(element)).toBe(false);
+  });
+});

src/utils/scroll/hasScroll.ts

@@ -0,0 +1,11 @@
+export const hasVerticalScroll = (element: HTMLElement): boolean => {
+  return element.scrollHeight > element.clientHeight;
+};
+
+export const hasHorizontalScroll = (element: HTMLElement): boolean => {
+  return element.scrollWidth > element.clientWidth;
+};
+
+export const hasScroll = (element: HTMLElement): boolean => {
+  return hasVerticalScroll(element) || hasHorizontalScroll(element);
+};

src/utils/scroll/index.ts

@@ -0,0 +1 @@
+export * from './hasScroll';