@instructure/ui-table 11.7.2-snapshot-50 → 11.7.2-snapshot-52

package/lib/Table/v2/index.js

@@ -56,21 +56,49 @@ let Table = exports.Table = (_dec = (0, _emotion.withStyle)(_styles.default), _d
   constructor(...args) {
     super(...args);
     this.ref = null;
+    // Reference to hidden aria-live region for announcing caption changes to screen readers
+    this._liveRegionRef = null;
+    // Timeout for delayed announcement (workaround for Safari/VoiceOver caption update bug)
+    this._announcementTimeout = void 0;
     this.handleRef = el => {
-      const elementRef = this.props.elementRef;
+      var _this$props$elementRe, _this$props;
       this.ref = el;
-      if (typeof elementRef === 'function') {
-        elementRef(el);
-      }
+      (_this$props$elementRe = (_this$props = this.props).elementRef) === null || _this$props$elementRe === void 0 ? void 0 : _this$props$elementRe.call(_this$props, el);
     };
   }
   componentDidMount() {
-    var _this$props$makeStyle, _this$props;
-    (_this$props$makeStyle = (_this$props = this.props).makeStyles) === null || _this$props$makeStyle === void 0 ? void 0 : _this$props$makeStyle.call(_this$props);
+    var _this$props$makeStyle, _this$props2;
+    (_this$props$makeStyle = (_this$props2 = this.props).makeStyles) === null || _this$props$makeStyle === void 0 ? void 0 : _this$props$makeStyle.call(_this$props2);
+  }
+  componentDidUpdate(prevProps) {
+    var _this$props$makeStyle2, _this$props3;
+    (_this$props$makeStyle2 = (_this$props3 = this.props).makeStyles) === null || _this$props$makeStyle2 === void 0 ? void 0 : _this$props$makeStyle2.call(_this$props3);
+    // Announce caption changes for screen readers (especially VoiceOver)
+    // Safari/VoiceOver has a known bug where dynamic <caption> updates aren't announced,
+    // so we use an aria-live region as a workaround
+    const prevSortInfo = this.getSortedHeaderInfo(prevProps);
+    const currentSortInfo = this.getSortedHeaderInfo(this.props);
+    // Only announce if sorting actually changed
+    const sortingChanged = (prevSortInfo === null || prevSortInfo === void 0 ? void 0 : prevSortInfo.header) !== (currentSortInfo === null || currentSortInfo === void 0 ? void 0 : currentSortInfo.header) || (prevSortInfo === null || prevSortInfo === void 0 ? void 0 : prevSortInfo.direction) !== (currentSortInfo === null || currentSortInfo === void 0 ? void 0 : currentSortInfo.direction);
+    if (sortingChanged && currentSortInfo && this._liveRegionRef) {
+      // Clear any pending announcement
+      clearTimeout(this._announcementTimeout);
+      // Clear the live region first (part of the clear-then-set pattern)
+      this._liveRegionRef.textContent = '';
+      // Wait 100ms before setting new content to ensure screen readers detect the change
+      this._announcementTimeout = setTimeout(() => {
+        if (this._liveRegionRef) {
+          const currentCaption = this.getCaptionText(this.props);
+          // Append non-breaking space (\u00A0) to force Safari/VoiceOver to treat
+          // repeated captions as different announcements
+          this._liveRegionRef.textContent = currentCaption + '\u00A0';
+        }
+      }, 100);
+    }
   }
-  componentDidUpdate() {
-    var _this$props$makeStyle2, _this$props2;
-    (_this$props$makeStyle2 = (_this$props2 = this.props).makeStyles) === null || _this$props$makeStyle2 === void 0 ? void 0 : _this$props$makeStyle2.call(_this$props2);
+  componentWillUnmount() {
+    // Clean up pending announcement timeout
+    clearTimeout(this._announcementTimeout);
   }
   getHeaders() {
     const _Children$toArray = _react.Children.toArray(this.props.children),
@@ -86,27 +114,64 @@ let Table = exports.Table = (_dec = (0, _emotion.withStyle)(_styles.default), _d
       return colHeader.props.children;
     });
   }
+  getSortedHeaderInfo(props) {
+    const _Children$toArray5 = _react.Children.toArray(props.children),
+      _Children$toArray6 = (0, _slicedToArray2.default)(_Children$toArray5, 1),
+      headChild = _Children$toArray6[0];
+    const _Children$toArray7 = _react.Children.toArray(/*#__PURE__*/(0, _react.isValidElement)(headChild) ? headChild.props.children : []),
+      _Children$toArray8 = (0, _slicedToArray2.default)(_Children$toArray7, 1),
+      firstRow = _Children$toArray8[0];
+    const colHeaders = _react.Children.toArray(/*#__PURE__*/(0, _react.isValidElement)(firstRow) ? firstRow.props.children : []);
+    // Find the column with an active sort direction
+    for (const colHeader of colHeaders) {
+      if (/*#__PURE__*/(0, _react.isValidElement)(colHeader) && colHeader.props.sortDirection && colHeader.props.sortDirection !== 'none') {
+        var _colHeader$props$chil, _colHeader$props$chil2, _colHeader$props$chil3;
+        // Extract header text (may be nested in child components)
+        const headerText = typeof colHeader.props.children === 'string' ? colHeader.props.children : (_colHeader$props$chil = (_colHeader$props$chil2 = colHeader.props.children) === null || _colHeader$props$chil2 === void 0 ? void 0 : (_colHeader$props$chil3 = _colHeader$props$chil2.props) === null || _colHeader$props$chil3 === void 0 ? void 0 : _colHeader$props$chil3.children) !== null && _colHeader$props$chil !== void 0 ? _colHeader$props$chil : '';
+        return {
+          header: headerText,
+          direction: colHeader.props.sortDirection
+        };
+      }
+    }
+    return null;
+  }
+  getCaptionText(props) {
+    const sortInfo = this.getSortedHeaderInfo(props);
+    const caption = props.caption;
+    if (!sortInfo) return caption;
+    const sortText = ` Sorted by ${sortInfo.header} (${sortInfo.direction})`;
+    return caption ? caption + sortText : sortText.trim();
+  }
   render() {
-    const _this$props3 = this.props,
-      margin = _this$props3.margin,
-      layout = _this$props3.layout,
-      caption = _this$props3.caption,
-      children = _this$props3.children,
-      hover = _this$props3.hover,
-      styles = _this$props3.styles,
-      minWidth = _this$props3.minWidth;
+    const _this$props4 = this.props,
+      margin = _this$props4.margin,
+      layout = _this$props4.layout,
+      caption = _this$props4.caption,
+      children = _this$props4.children,
+      hover = _this$props4.hover,
+      styles = _this$props4.styles,
+      minWidth = _this$props4.minWidth;
     const isStacked = layout === 'stacked';
-    const headers = isStacked ? this.getHeaders() : void 0;
+    const captionText = this.getCaptionText(this.props);
     if (!caption) {
       (0, _console.error)(false, `[Table] required prop caption is not set.`);
     }
-    return (0, _jsxRuntime.jsx)(_TableContext.default.Provider, {
+    return (0, _jsxRuntime.jsxs)(_TableContext.default.Provider, {
       value: {
-        isStacked: isStacked,
+        isStacked,
         hover: hover,
-        headers: headers
+        headers: isStacked ? this.getHeaders() : void 0
       },
-      children: (0, _jsxRuntime.jsxs)(_latest.View
+      children: [(0, _jsxRuntime.jsx)("div", {
+        ref: el => {
+          this._liveRegionRef = el;
+        },
+        "aria-live": "polite",
+        "aria-atomic": "true",
+        role: "status",
+        css: styles === null || styles === void 0 ? void 0 : styles.liveRegion
+      }), (0, _jsxRuntime.jsxs)(_latest.View
       // All HTML props, except the ones accepted by `View` and `Table`
       , {
         ..._latest.View.omitViewProps((0, _omitProps.omitProps)(this.props, Table.allowedProps), Table),
@@ -116,20 +181,15 @@ let Table = exports.Table = (_dec = (0, _emotion.withStyle)(_styles.default), _d
         elementRef: this.handleRef,
         css: styles === null || styles === void 0 ? void 0 : styles.table,
         role: isStacked ? 'table' : void 0,
-        "aria-label": isStacked ? caption : void 0,
-        children: [!isStacked && (0, _jsxRuntime.jsx)("caption", {
+        "aria-label": captionText,
+        children: [!isStacked && caption && (0, _jsxRuntime.jsx)("caption", {
           children: (0, _jsxRuntime.jsx)(_ScreenReaderContent.ScreenReaderContent, {
-            children: caption
+            children: captionText
           })
-        }), _react.Children.map(children, child => {
-          if (/*#__PURE__*/(0, _react.isValidElement)(child)) {
-            return (0, _safeCloneElement.safeCloneElement)(child, {
-              key: child.props.name
-            });
-          }
-          return child;
-        })]
-      })
+        }), _react.Children.map(children, child => /*#__PURE__*/(0, _react.isValidElement)(child) ? (0, _safeCloneElement.safeCloneElement)(child, {
+          key: child.props.name
+        }) : child)]
+      })]
     });
   }
 }, _Table.displayName = "Table", _Table.componentId = 'Table', _Table.allowedProps = _props.allowedProps, _Table.defaultProps = {

package/lib/Table/v2/styles.js

@@ -58,6 +58,14 @@ const generateStyle = (componentTheme, props, _sharedTokens) => {
       caption: {
         textAlign: 'start'
       }
+    },
+    liveRegion: {
+      label: 'table__liveRegion',
+      position: 'absolute',
+      left: '-10000px',
+      width: '1px',
+      height: '1px',
+      overflow: 'hidden'
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-table",
-  "version": "11.7.2-snapshot-50",
+  "version": "11.7.2-snapshot-52",
   "description": "A styled HTML table component",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -15,25 +15,25 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.27.6",
-    "@instructure/console": "11.7.2-snapshot-50",
-    "@instructure/emotion": "11.7.2-snapshot-50",
-    "@instructure/shared-types": "11.7.2-snapshot-50",
-    "@instructure/ui-icons": "11.7.2-snapshot-50",
-    "@instructure/ui-a11y-content": "11.7.2-snapshot-50",
-    "@instructure/ui-react-utils": "11.7.2-snapshot-50",
-    "@instructure/ui-simple-select": "11.7.2-snapshot-50",
-    "@instructure/ui-view": "11.7.2-snapshot-50",
-    "@instructure/ui-utils": "11.7.2-snapshot-50"
+    "@instructure/emotion": "11.7.2-snapshot-52",
+    "@instructure/ui-a11y-content": "11.7.2-snapshot-52",
+    "@instructure/ui-icons": "11.7.2-snapshot-52",
+    "@instructure/console": "11.7.2-snapshot-52",
+    "@instructure/shared-types": "11.7.2-snapshot-52",
+    "@instructure/ui-react-utils": "11.7.2-snapshot-52",
+    "@instructure/ui-simple-select": "11.7.2-snapshot-52",
+    "@instructure/ui-utils": "11.7.2-snapshot-52",
+    "@instructure/ui-view": "11.7.2-snapshot-52"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "15.0.7",
     "@testing-library/user-event": "^14.6.1",
     "vitest": "^3.2.2",
-    "@instructure/ui-axe-check": "11.7.2-snapshot-50",
-    "@instructure/ui-babel-preset": "11.7.2-snapshot-50",
-    "@instructure/ui-themes": "11.7.2-snapshot-50",
-    "@instructure/ui-color-utils": "11.7.2-snapshot-50"
+    "@instructure/ui-babel-preset": "11.7.2-snapshot-52",
+    "@instructure/ui-themes": "11.7.2-snapshot-52",
+    "@instructure/ui-color-utils": "11.7.2-snapshot-52",
+    "@instructure/ui-axe-check": "11.7.2-snapshot-52"
   },
   "peerDependencies": {
     "react": ">=18 <=19"

package/src/Table/v1/README.md

@@ -351,10 +351,7 @@ const SortableTable = ({ caption, headers, rows }) => {
             </View>
           )}
 
-          <Table
-            caption={`${caption}: sorted by ${sortBy} in ${direction} order`}
-            {...props}
-          >
+          <Table caption={caption} {...props}>
             <Table.Head renderSortLabel="Sort by">
               {renderHeaderRow(direction)}
             </Table.Head>
@@ -370,13 +367,6 @@ const SortableTable = ({ caption, headers, rows }) => {
               ))}
             </Table.Body>
           </Table>
-          <Alert
-            liveRegion={() => document.getElementById('flash-messages')}
-            liveRegionPoliteness="polite"
-            screenReaderOnly
-          >
-            {`Sorted by ${sortBy} in ${direction} order`}
-          </Alert>
         </div>
       )}
     </Responsive>
@@ -505,10 +495,7 @@ const SelectableTable = ({
           <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 caption={caption} {...props}>
             <Table.Head
               renderSortLabel={
                 <ScreenReaderContent>Sort by</ScreenReaderContent>
@@ -685,15 +672,6 @@ const SortableTable = ({ caption, headers, rows, perPage }) => {
         ascending={ascending}
         perPage={perPage}
       />
-      <Alert
-        liveRegion={() => document.getElementById('flash-messages')}
-        liveRegionPoliteness="polite"
-        screenReaderOnly
-      >
-        {`Sorted by ${sortBy} in ${
-          ascending ? 'ascending' : 'descending'
-        } order`}
-      </Alert>
     </div>
   )
 }

package/src/Table/v1/index.tsx

@@ -71,23 +71,51 @@ class Table extends Component<TableProps> {
   static Cell = Cell
 
   ref: Element | null = null
+  // Reference to hidden aria-live region for announcing caption changes to screen readers
+  _liveRegionRef: HTMLDivElement | null = null
+  // Timeout for delayed announcement (workaround for Safari/VoiceOver caption update bug)
+  _announcementTimeout?: ReturnType<typeof setTimeout>
 
   handleRef = (el: Element | null) => {
-    const { elementRef } = this.props
-
     this.ref = el
-
-    if (typeof elementRef === 'function') {
-      elementRef(el)
-    }
+    this.props.elementRef?.(el)
   }
 
   componentDidMount() {
     this.props.makeStyles?.()
   }
 
-  componentDidUpdate() {
+  componentDidUpdate(prevProps: TableProps) {
     this.props.makeStyles?.()
+    // Announce caption changes for screen readers (especially VoiceOver)
+    // Safari/VoiceOver has a known bug where dynamic <caption> updates aren't announced,
+    // so we use an aria-live region as a workaround
+    const prevSortInfo = this.getSortedHeaderInfo(prevProps)
+    const currentSortInfo = this.getSortedHeaderInfo(this.props)
+    // Only announce if sorting actually changed
+    const sortingChanged =
+      prevSortInfo?.header !== currentSortInfo?.header ||
+      prevSortInfo?.direction !== currentSortInfo?.direction
+    if (sortingChanged && currentSortInfo && this._liveRegionRef) {
+      // Clear any pending announcement
+      clearTimeout(this._announcementTimeout)
+      // Clear the live region first (part of the clear-then-set pattern)
+      this._liveRegionRef.textContent = ''
+      // Wait 100ms before setting new content to ensure screen readers detect the change
+      this._announcementTimeout = setTimeout(() => {
+        if (this._liveRegionRef) {
+          const currentCaption = this.getCaptionText(this.props)
+          // Append non-breaking space (\u00A0) to force Safari/VoiceOver to treat
+          // repeated captions as different announcements
+          this._liveRegionRef.textContent = currentCaption + '\u00A0'
+        }
+      }, 100)
+    }
+  }
+
+  componentWillUnmount() {
+    // Clean up pending announcement timeout
+    clearTimeout(this._announcementTimeout)
   }
 
   getHeaders() {
@@ -106,11 +134,45 @@ class Table extends Component<TableProps> {
     )
   }
 
+  getSortedHeaderInfo(props: TableProps) {
+    const [headChild] = Children.toArray(props.children)
+    const [firstRow] = Children.toArray(
+      isValidElement(headChild) ? headChild.props.children : []
+    )
+    const colHeaders = Children.toArray(
+      isValidElement(firstRow) ? firstRow.props.children : []
+    )
+    // Find the column with an active sort direction
+    for (const colHeader of colHeaders) {
+      if (
+        isValidElement(colHeader) &&
+        colHeader.props.sortDirection &&
+        colHeader.props.sortDirection !== 'none'
+      ) {
+        // Extract header text (may be nested in child components)
+        const headerText =
+          typeof colHeader.props.children === 'string'
+            ? colHeader.props.children
+            : colHeader.props.children?.props?.children ?? ''
+        return { header: headerText, direction: colHeader.props.sortDirection }
+      }
+    }
+    return null
+  }
+
+  getCaptionText(props: TableProps) {
+    const sortInfo = this.getSortedHeaderInfo(props)
+    const caption = props.caption as string
+    if (!sortInfo) return caption
+    const sortText = ` Sorted by ${sortInfo.header} (${sortInfo.direction})`
+    return caption ? caption + sortText : sortText.trim()
+  }
+
   render() {
     const { margin, layout, caption, children, hover, styles, minWidth } =
       this.props
     const isStacked = layout === 'stacked'
-    const headers = isStacked ? this.getHeaders() : undefined
+    const captionText = this.getCaptionText(this.props)
 
     if (!caption) {
       error(false, `[Table] required prop caption is not set.`)
@@ -119,11 +181,23 @@ class Table extends Component<TableProps> {
     return (
       <TableContext.Provider
         value={{
-          isStacked: isStacked,
+          isStacked,
           hover: hover!,
-          headers: headers
+          headers: isStacked ? this.getHeaders() : undefined
         }}
       >
+        {/* ARIA live region for dynamic sort announcements.
+            MUST be outside <table> due to Safari/VoiceOver bug.
+            Empty on page load, populated only when sorting changes. */}
+        <div
+          ref={(el) => {
+            this._liveRegionRef = el
+          }}
+          aria-live="polite"
+          aria-atomic="true"
+          role="status"
+          css={styles?.liveRegion}
+        />
         <View
           // All HTML props, except the ones accepted by `View` and `Table`
           {...View.omitViewProps(
@@ -136,21 +210,21 @@ class Table extends Component<TableProps> {
           elementRef={this.handleRef}
           css={styles?.table}
           role={isStacked ? 'table' : undefined}
-          aria-label={isStacked ? (caption as string) : undefined}
+          aria-label={captionText}
         >
-          {!isStacked && (
+          {/* Caption for visual display and semantic HTML */}
+          {!isStacked && caption && (
             <caption>
-              <ScreenReaderContent>{caption}</ScreenReaderContent>
+              <ScreenReaderContent>{captionText}</ScreenReaderContent>
             </caption>
           )}
-          {Children.map(children, (child) => {
-            if (isValidElement(child)) {
-              return safeCloneElement(child, {
-                key: (child as ReactElement<any>).props.name
-              })
-            }
-            return child
-          })}
+          {Children.map(children, (child) =>
+            isValidElement(child)
+              ? safeCloneElement(child, {
+                  key: (child as ReactElement<any>).props.name
+                })
+              : child
+          )}
         </View>
       </TableContext.Provider>
     )

package/src/Table/v1/props.ts

@@ -79,7 +79,7 @@ type TableProps = TableOwnProps &
   WithStyleProps<TableTheme, TableStyle> &
   OtherHTMLAttributes<TableOwnProps>
 
-type TableStyle = ComponentStyle<'table'>
+type TableStyle = ComponentStyle<'table' | 'liveRegion'>
 const allowedProps: AllowedPropKeys = [
   'caption',
   'children',

package/src/Table/v1/styles.ts

@@ -55,6 +55,14 @@ const generateStyle = (
       borderSpacing: 0,
       ...(layout === 'fixed' && { tableLayout: 'fixed' }),
       caption: { textAlign: 'start' }
+    },
+    liveRegion: {
+      label: 'table__liveRegion',
+      position: 'absolute',
+      left: '-10000px',
+      width: '1px',
+      height: '1px',
+      overflow: 'hidden'
     }
   }
 }

package/src/Table/v2/README.md

@@ -351,10 +351,7 @@ const SortableTable = ({ caption, headers, rows }) => {
             </View>
           )}
 
-          <Table
-            caption={`${caption}: sorted by ${sortBy} in ${direction} order`}
-            {...props}
-          >
+          <Table caption={caption} {...props}>
             <Table.Head renderSortLabel="Sort by">
               {renderHeaderRow(direction)}
             </Table.Head>
@@ -370,13 +367,6 @@ const SortableTable = ({ caption, headers, rows }) => {
               ))}
             </Table.Body>
           </Table>
-          <Alert
-            liveRegion={() => document.getElementById('flash-messages')}
-            liveRegionPoliteness="polite"
-            screenReaderOnly
-          >
-            {`Sorted by ${sortBy} in ${direction} order`}
-          </Alert>
         </div>
       )}
     </Responsive>
@@ -505,10 +495,7 @@ const SelectableTable = ({
           <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 caption={caption} {...props}>
             <Table.Head
               renderSortLabel={
                 <ScreenReaderContent>Sort by</ScreenReaderContent>
@@ -685,15 +672,6 @@ const SortableTable = ({ caption, headers, rows, perPage }) => {
         ascending={ascending}
         perPage={perPage}
       />
-      <Alert
-        liveRegion={() => document.getElementById('flash-messages')}
-        liveRegionPoliteness="polite"
-        screenReaderOnly
-      >
-        {`Sorted by ${sortBy} in ${
-          ascending ? 'ascending' : 'descending'
-        } order`}
-      </Alert>
     </div>
   )
 }