feat(ui-table): add column ordering to caption

INSTUI-4699

Author: joyenjoyer

packages/ui-table/src/Table/README.md

@@ -582,10 +582,7 @@ By default, the options in the `Select` for sorting in stacked layout are genera
                 </View>
               )}
 
-              <Table
-                caption={`${caption}: sorted by ${sortBy} in ${direction} order`}
-                {...props}
-              >
+              <Table {...props}>
                 <Table.Head renderSortLabel="Sort by">
                   {this.renderHeaderRow(direction)}
                 </Table.Head>
@@ -601,13 +598,6 @@ By default, the options in the `Select` for sorting in stacked layout are genera
                   ))}
                 </Table.Body>
               </Table>
-              <Alert
-                liveRegion={() => document.getElementById('flash-messages')}
-                liveRegionPoliteness="polite"
-                screenReaderOnly
-              >
-                {`Sorted by ${sortBy} in ${direction} order`}
-              </Alert>
             </div>
           )}
         </Responsive>
@@ -806,10 +796,7 @@ By default, the options in the `Select` for sorting in stacked layout are genera
               </View>
             )}
 
-            <Table
-              caption={`${caption}: sorted by ${sortBy} in ${direction} order`}
-              {...props}
-            >
+            <Table {...props}>
               <Table.Head renderSortLabel="Sort by">
                 {renderHeaderRow(direction)}
               </Table.Head>
@@ -825,13 +812,6 @@ By default, the options in the `Select` for sorting in stacked layout are genera
                 ))}
               </Table.Body>
             </Table>
-            <Alert
-              liveRegion={() => document.getElementById('flash-messages')}
-              liveRegionPoliteness="polite"
-              screenReaderOnly
-            >
-              {`Sorted by ${sortBy} in ${direction} order`}
-            </Alert>
           </div>
         )}
       </Responsive>
@@ -966,10 +946,7 @@ that selection does not re-paginate or re-sort the table, and pagination does no
               <View as="div" padding="small" background="primary-inverse">
                 {`${selected.size} of ${rowIds.length} selected`}
               </View>
-              <Table
-                caption={`${caption}: sorted by ${sortBy} in ${direction} order`}
-                {...props}
-              >
+              <Table {...props}>
                 <Table.Head
                   renderSortLabel={
                     <ScreenReaderContent>Sort by</ScreenReaderContent>
@@ -1175,15 +1152,6 @@ that selection does not re-paginate or re-sort the table, and pagination does no
             ascending={ascending}
             perPage={perPage}
           />
-          <Alert
-            liveRegion={() => document.getElementById('flash-messages')}
-            liveRegionPoliteness="polite"
-            screenReaderOnly
-          >
-            {`Sorted by ${sortBy} in ${
-              ascending ? 'ascending' : 'descending'
-            } order`}
-          </Alert>
         </div>
       )
     }
@@ -1305,10 +1273,7 @@ that selection does not re-paginate or re-sort the table, and pagination does no
             <View as="div" padding="small" background="primary-inverse">
               {`${selected.size} of ${rowIds.length} selected`}
             </View>
-            <Table
-              caption={`${caption}: sorted by ${sortBy} in ${direction} order`}
-              {...props}
-            >
+            <Table {...props}>
               <Table.Head
                 renderSortLabel={
                   <ScreenReaderContent>Sort by</ScreenReaderContent>
@@ -1485,15 +1450,6 @@ that selection does not re-paginate or re-sort the table, and pagination does no
           ascending={ascending}
           perPage={perPage}
         />
-        <Alert
-          liveRegion={() => document.getElementById('flash-messages')}
-          liveRegionPoliteness="polite"
-          screenReaderOnly
-        >
-          {`Sorted by ${sortBy} in ${
-            ascending ? 'ascending' : 'descending'
-          } order`}
-        </Alert>
       </div>
     )
   }

packages/ui-table/src/Table/index.tsx

@@ -101,11 +101,46 @@ class Table extends Component<TableProps> {
     })
   }
 
+  getSortedHeaderInfo() {
+    const [headChild] = Children.toArray(this.props.children)
+    if (!headChild || !isValidElement(headChild)) return null
+    const [firstRow] = Children.toArray(headChild.props.children)
+    if (!firstRow || !isValidElement(firstRow)) return null
+    const colHeaders = Children.toArray(firstRow.props.children)
+    for (const colHeader of colHeaders) {
+      if (
+        isValidElement(colHeader) &&
+        colHeader.props.sortDirection &&
+        colHeader.props.sortDirection !== 'none'
+      ) {
+        const headerText =
+          typeof colHeader.props.children === 'string'
+            ? colHeader.props.children
+            : colHeader.props.children?.props?.children ?? ''
+        return {
+          header: headerText,
+          direction: colHeader.props.sortDirection
+        }
+      }
+    }
+    return null
+  }
+
   render() {
     const { margin, layout, caption, children, hover, styles } = this.props
     const isStacked = layout === 'stacked'
     const headers = isStacked ? this.getHeaders() : undefined
 
+    // Add sorting info to caption for screen readers
+    const sortedHeaderInfo = this.getSortedHeaderInfo()
+    let captionText = caption as string
+    if (sortedHeaderInfo) {
+      captionText = caption
+        ? caption +
+          ` Sorted by ${sortedHeaderInfo.header} (${sortedHeaderInfo.direction})`
+        : `Sorted by ${sortedHeaderInfo.header} (${sortedHeaderInfo.direction})`
+    }
+
     return (
       <TableContext.Provider
         value={{
@@ -124,12 +159,28 @@ class Table extends Component<TableProps> {
           elementRef={this.handleRef}
           css={styles?.table}
           role={isStacked ? 'table' : undefined}
-          aria-label={isStacked ? (caption as string) : undefined}
+          aria-label={isStacked ? captionText : undefined}
         >
           {!isStacked && (
-            <caption>
-              <ScreenReaderContent>{caption}</ScreenReaderContent>
-            </caption>
+            <>
+              <caption>
+                <ScreenReaderContent>{captionText}</ScreenReaderContent>
+              </caption>
+              {sortedHeaderInfo && (
+                <div
+                  aria-live="polite"
+                  style={{
+                    position: 'absolute',
+                    width: 1,
+                    height: 1,
+                    overflow: 'hidden',
+                    clip: 'rect(1px, 1px, 1px, 1px)'
+                  }}
+                >
+                  {captionText}
+                </div>
+              )}
+            </>
           )}
           {Children.map(children, (child) => {
             if (isValidElement(child)) {