@instructure/ui-table 9.7.2 → 9.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-table",
-  "version": "9.7.2",
+  "version": "9.8.0",
   "description": "A styled HTML table component",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@instructure/ui-axe-check": "9.7.2",
-    "@instructure/ui-babel-preset": "9.7.2",
-    "@instructure/ui-color-utils": "9.7.2",
-    "@instructure/ui-test-utils": "9.7.2",
-    "@instructure/ui-themes": "9.7.2",
+    "@instructure/ui-axe-check": "9.8.0",
+    "@instructure/ui-babel-preset": "9.8.0",
+    "@instructure/ui-color-utils": "9.8.0",
+    "@instructure/ui-test-utils": "9.8.0",
+    "@instructure/ui-themes": "9.8.0",
     "@testing-library/jest-dom": "^6.4.6",
     "@testing-library/react": "^15.0.7",
     "@testing-library/user-event": "^14.5.2",
@@ -35,17 +35,17 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.24.5",
-    "@instructure/console": "9.7.2",
-    "@instructure/emotion": "9.7.2",
-    "@instructure/shared-types": "9.7.2",
-    "@instructure/ui-a11y-content": "9.7.2",
-    "@instructure/ui-icons": "9.7.2",
-    "@instructure/ui-prop-types": "9.7.2",
-    "@instructure/ui-react-utils": "9.7.2",
-    "@instructure/ui-simple-select": "9.7.2",
-    "@instructure/ui-testable": "9.7.2",
-    "@instructure/ui-utils": "9.7.2",
-    "@instructure/ui-view": "9.7.2",
+    "@instructure/console": "9.8.0",
+    "@instructure/emotion": "9.8.0",
+    "@instructure/shared-types": "9.8.0",
+    "@instructure/ui-a11y-content": "9.8.0",
+    "@instructure/ui-icons": "9.8.0",
+    "@instructure/ui-prop-types": "9.8.0",
+    "@instructure/ui-react-utils": "9.8.0",
+    "@instructure/ui-simple-select": "9.8.0",
+    "@instructure/ui-testable": "9.8.0",
+    "@instructure/ui-utils": "9.8.0",
+    "@instructure/ui-view": "9.8.0",
     "prop-types": "^15.8.1"
   },
   "peerDependencies": {

package/src/Table/Body/index.tsx

@@ -23,7 +23,7 @@
  */
 
 /** @jsx jsx */
-import { Component, Children, isValidElement } from 'react'
+import { Component, Children, ContextType, isValidElement } from 'react'
 
 import { safeCloneElement, omitProps } from '@instructure/ui-react-utils'
 import { View } from '@instructure/ui-view'
@@ -32,8 +32,8 @@ import { withStyle, jsx } from '@instructure/emotion'
 import generateStyle from './styles'
 import generateComponentTheme from './theme'
 import type { TableBodyProps } from './props'
-import type { RowChild } from '../props'
 import { allowedProps, propTypes } from './props'
+import TableContext from '../TableContext'
 
 /**
 ---
@@ -44,10 +44,10 @@ id: Table.Body
 @withStyle(generateStyle, generateComponentTheme)
 class Body extends Component<TableBodyProps> {
   static readonly componentId = 'Table.Body'
-
+  static contextType = TableContext
+  declare context: ContextType<typeof TableContext>
   static allowedProps = allowedProps
   static propTypes = propTypes
-
   static defaultProps = {
     children: null
   }
@@ -61,7 +61,8 @@ class Body extends Component<TableBodyProps> {
   }
 
   render() {
-    const { children, hover, isStacked, headers, styles } = this.props
+    const { children, styles } = this.props
+    const { isStacked, hover, headers } = this.context
 
     return (
       <View
@@ -70,12 +71,18 @@ class Body extends Component<TableBodyProps> {
         css={styles?.body}
         role={isStacked ? 'rowgroup' : undefined}
       >
-        {Children.map(children as RowChild[], (child) => {
+        {Children.map(children, (child) => {
           if (isValidElement(child)) {
             return safeCloneElement(child, {
               key: child.props.name,
-              isStacked,
+              // Sent down for compatibility with custom components
+              // TODO DEPRECATED, remove in v11
               hover,
+              // Sent down for compatibility with custom components
+              // TODO DEPRECATED, remove in v11
+              isStacked,
+              // Sent down for compatibility with custom components
+              // TODO DEPRECATED, remove in v11
               headers
             })
           }

package/src/Table/Body/props.ts

@@ -24,8 +24,6 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 
-import type { TableRowProps } from '../Row/props'
-
 import type {
   OtherHTMLAttributes,
   PropValidators,
@@ -34,11 +32,11 @@ import type {
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
 
 type TableBodyOwnProps = {
-  hover?: boolean
-  isStacked?: boolean
-  headers?: TableRowProps['headers']
   /**
-   * `Table.Row`
+   * Body's children should be a container component where each child represents
+   * a row.
+   *
+   * `Table.Row` by default
    */
   children?: React.ReactNode
 }
@@ -54,20 +52,10 @@ type TableBodyProps = TableBodyOwnProps &
 type TableBodyStyle = ComponentStyle<'body'>
 
 const propTypes: PropValidators<PropKeys> = {
-  children: PropTypes.node,
-  hover: PropTypes.bool,
-  isStacked: PropTypes.bool,
-  headers: PropTypes.arrayOf(
-    PropTypes.oneOfType([PropTypes.node, PropTypes.func])
-  )
+  children: PropTypes.node
 }
 
-const allowedProps: AllowedPropKeys = [
-  'children',
-  'hover',
-  'isStacked',
-  'headers'
-]
+const allowedProps: AllowedPropKeys = ['children']
 
 export type { TableBodyProps, TableBodyStyle }
 export { propTypes, allowedProps }

package/src/Table/Body/styles.ts

@@ -31,8 +31,6 @@ import type { TableBodyStyle } from './props'
  * ---
  * Generates the style object from the theme and provided additional information
  * @param  {Object} componentTheme The theme variable object.
- * @param  {Object} props the props of the component, the style is applied to
- * @param  {Object} state the state of the component, the style is applied to
  * @return {Object} The final style object, which will be used in the component
  */
 const generateStyle = (componentTheme: TableBodyTheme): TableBodyStyle => {

package/src/Table/Cell/index.tsx

@@ -23,7 +23,7 @@
  */
 
 /** @jsx jsx */
-import { Component } from 'react'
+import { Component, ContextType } from 'react'
 
 import { omitProps, callRenderProp } from '@instructure/ui-react-utils'
 import { View } from '@instructure/ui-view'
@@ -34,6 +34,7 @@ import generateStyle from './styles'
 import generateComponentTheme from './theme'
 import type { TableCellProps } from './props'
 import { allowedProps, propTypes } from './props'
+import TableContext from '../TableContext'
 
 /**
 ---
@@ -44,7 +45,8 @@ id: Table.Cell
 @withStyle(generateStyle, generateComponentTheme)
 class Cell extends Component<TableCellProps> {
   static readonly componentId = 'Table.Cell'
-
+  static contextType = TableContext
+  declare context: ContextType<typeof TableContext>
   static allowedProps = allowedProps
   static propTypes = propTypes
 
@@ -62,7 +64,8 @@ class Cell extends Component<TableCellProps> {
   }
 
   render() {
-    const { children, styles, isStacked, header } = this.props
+    const { children, styles, header } = this.props
+    const isStacked = this.context.isStacked
 
     return (
       <View

package/src/Table/Cell/props.ts

@@ -33,10 +33,14 @@ import type {
 } from '@instructure/shared-types'
 
 type TableCellOwnProps = {
-  isStacked?: boolean
+  /**
+   * Contains the column header for this cell.
+   * This gets rendered in `stacked` layout to identify the column the data
+   * belongs to.
+   */
   header?: Renderable
   /**
-   * Control the text alignment in cell
+   * Controls the text alignment in cell.
    */
   textAlign?: 'start' | 'center' | 'end'
   children?: Renderable
@@ -54,17 +58,11 @@ type TableCellStyle = ComponentStyle<'cell'>
 
 const propTypes: PropValidators<PropKeys> = {
   children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
-  isStacked: PropTypes.bool,
   header: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
   textAlign: PropTypes.oneOf(['start', 'center', 'end'])
 }
 
-const allowedProps: AllowedPropKeys = [
-  'children',
-  'isStacked',
-  'header',
-  'textAlign'
-]
+const allowedProps: AllowedPropKeys = ['children', 'header', 'textAlign']
 
 export type { TableCellProps, TableCellStyle }
 export { propTypes, allowedProps }

package/src/Table/ColHeader/props.ts

@@ -32,6 +32,10 @@ import type {
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
 
 type TableColHeaderOwnProps = {
+  /**
+   * DEPRECATED. Use `TableContext` to read this value
+   */
+  isStacked?: boolean
   /**
    * A unique id for this column. The `id` is also used as option in combobox,
    * when sortable table is in stacked layout,
@@ -52,18 +56,18 @@ type TableColHeaderOwnProps = {
    */
   textAlign?: 'start' | 'center' | 'end'
   /**
-   * The string of sorting direction
+   * The sorting direction
    */
   sortDirection?: 'none' | 'ascending' | 'descending'
   /**
-   * Callback fired when column header is clicked. Parameters: `(event, { id })`
+   * Callback fired when column header is clicked.
    */
   onRequestSort?: (
     event: React.SyntheticEvent,
     param: { id: TableColHeaderOwnProps['id'] }
   ) => void
   /**
-   * The column header scope attribute. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th#attr-scope
+   * The column header scope attribute. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th#scope
    */
   scope?: 'row' | 'col' | 'rowgroup' | 'colgroup' | 'auto'
   children?: React.ReactNode
@@ -85,6 +89,7 @@ type TableColHeaderStyle = ComponentStyle<
 >
 
 const propTypes: PropValidators<PropKeys> = {
+  isStacked: PropTypes.bool,
   id: PropTypes.string.isRequired,
   stackedSortByLabel: PropTypes.string,
   children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
@@ -97,6 +102,7 @@ const propTypes: PropValidators<PropKeys> = {
 
 const allowedProps: AllowedPropKeys = [
   'id',
+  'isStacked',
   'stackedSortByLabel',
   'children',
   'width',

package/src/Table/Head/index.tsx

@@ -23,13 +23,9 @@
  */
 
 /** @jsx jsx */
-import { Component, Children } from 'react'
+import { Component, Children, ContextType } from 'react'
 
-import {
-  omitProps,
-  matchComponentTypes,
-  callRenderProp
-} from '@instructure/ui-react-utils'
+import { omitProps, callRenderProp } from '@instructure/ui-react-utils'
 import { SimpleSelect } from '@instructure/ui-simple-select'
 import type { SimpleSelectProps } from '@instructure/ui-simple-select'
 import { ScreenReaderContent } from '@instructure/ui-a11y-content'
@@ -41,12 +37,11 @@ import { withStyle, jsx } from '@instructure/emotion'
 import generateStyle from './styles'
 import generateComponentTheme from './theme'
 
-import { Row } from '../Row'
-import { ColHeader } from '../ColHeader'
 import type { TableColHeaderProps } from '../ColHeader/props'
 import type { TableHeadProps } from './props'
-import type { ColHeaderChild, RowChild } from '../props'
+import type { RowChild } from '../props'
 import { allowedProps, propTypes } from './props'
+import TableContext from '../TableContext'
 
 /**
 ---
@@ -57,26 +52,28 @@ id: Table.Head
 @withStyle(generateStyle, generateComponentTheme)
 class Head extends Component<TableHeadProps> {
   static readonly componentId = 'Table.Head'
-
+  static contextType = TableContext
+  declare context: ContextType<typeof TableContext>
   static allowedProps = allowedProps
   static propTypes = propTypes
-
   static defaultProps = {
     children: null
   }
 
+  /**
+   * Returns `true` if the first child's children have a `onRequestSort` prop
+   */
   get isSortable() {
-    const [row] = Children.toArray(this.props.children) as RowChild[]
+    const [firstRow] = Children.toArray(this.props.children) as RowChild[]
     let sortable = false
-
-    if (row) {
-      Children.forEach(row.props.children as ColHeaderChild[], (colHeader) => {
-        if (matchComponentTypes<ColHeaderChild>(colHeader, [ColHeader])) {
-          if (colHeader.props.onRequestSort) sortable = true
+    if (firstRow && firstRow.props && firstRow.props.children) {
+      Children.forEach(firstRow.props.children, (grandchild) => {
+        if (grandchild.props.onRequestSort) {
+          sortable = true
+          return
         }
       })
     }
-
     return sortable
   }
 
@@ -94,13 +91,19 @@ class Head extends Component<TableHeadProps> {
     this.props.makeStyles?.()
   }
 
+  /**
+   * This `Select` is used in `stacked` layout. It's populated by iterating
+   * through the first child's children (by default `ColHeader`) and reading
+   * there the `id`, `stackedSortByLabel`, `sortDirection`, `onRequestSort` props
+   */
   renderSelect() {
     const { children, renderSortLabel } = this.props
-    const [row] = Children.toArray(children) as RowChild[]
+    const [firstRow] = Children.toArray(children) as RowChild[]
 
-    if (!matchComponentTypes<RowChild>(row, [Row])) {
+    if (!firstRow?.props?.children) {
       return null
     }
+
     const options: {
       id: TableColHeaderProps['id']
       label:
@@ -113,21 +116,17 @@ class Head extends Component<TableHeadProps> {
     > = {}
     let selectedOption: TableColHeaderProps['id'] | undefined
     let count = 0
-
-    Children.forEach(row.props.children, (colHeader) => {
+    Children.forEach(firstRow.props.children, (grandchild) => {
       count += 1
-      if (matchComponentTypes<ColHeaderChild>(colHeader, [ColHeader])) {
-        const { id, stackedSortByLabel, sortDirection, onRequestSort } =
-          colHeader.props
-
+      if (!grandchild.props) return
+      const { id, stackedSortByLabel, sortDirection, onRequestSort } =
+        grandchild.props
+      if (id && onRequestSort) {
         const label = stackedSortByLabel || id
-
-        if (onRequestSort) {
-          options.push({ id, label })
-          clickHandlers[id] = onRequestSort
-          if (sortDirection !== 'none') {
-            selectedOption = id
-          }
+        options.push({ id, label })
+        clickHandlers[id] = onRequestSort
+        if (sortDirection !== 'none') {
+          selectedOption = id
         }
       }
     })
@@ -177,15 +176,16 @@ class Head extends Component<TableHeadProps> {
   }
 
   render() {
-    const { children, isStacked, styles } = this.props
-
-    return isStacked ? (
+    const { children, styles } = this.props
+    return this.context.isStacked ? (
       this.renderSelect()
     ) : (
-      <thead {...omitProps(this.props, Head.allowedProps)} css={styles?.head}>
-        {Children.map(children, (child) =>
-          matchComponentTypes<RowChild>(child, [Row]) ? child : null
-        )}
+      // TODO remove 'hover' exclude in v11, its passed down for compatibility with custom components
+      <thead
+        {...omitProps(this.props, Head.allowedProps, ['hover'])}
+        css={styles?.head}
+      >
+        {children}
       </thead>
     )
   }

package/src/Table/Head/props.ts

@@ -22,7 +22,6 @@
  * SOFTWARE.
  */
 
-import React from 'react'
 import PropTypes from 'prop-types'
 
 import type {
@@ -32,14 +31,30 @@ import type {
   TableHeadTheme
 } from '@instructure/shared-types'
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import { RowChild } from '../props'
 
 type TableHeadOwnProps = {
-  isStacked?: boolean
+  /**
+   * The sort `Select`'s label when using `stacked` layout and the table is
+   * sortable.
+   * If you don't want to display anything you should use `ScreenReaderContent`
+   * so screen readers can read the `Select`'s purpose
+   */
   renderSortLabel?: Renderable
   /**
-   * `Table.Row`
+   * The header row(s).
+   * Default type: `Table.Row`
+   *
+   * Its first child is treated specially if the table is sortable and has
+   * `stacked` layout:
+   *
+   * A `Select` is created which reads options from the first child's
+   * children, that tries to read the following props: `id`,
+   * `stackedSortByLabel`,`sortDirection`, `onRequestSort` (Available on
+   * `Table.ColHeader`).
+   * These are used to sort the table in this layout.
    */
-  children?: React.ReactNode
+  children?: RowChild
 }
 type PropKeys = keyof TableHeadOwnProps
 
@@ -53,15 +68,10 @@ type TableHeadStyle = ComponentStyle<'head'>
 
 const propTypes: PropValidators<PropKeys> = {
   children: PropTypes.node,
-  isStacked: PropTypes.bool,
   renderSortLabel: PropTypes.oneOfType([PropTypes.node, PropTypes.func])
 }
 
-const allowedProps: AllowedPropKeys = [
-  'children',
-  'isStacked',
-  'renderSortLabel'
-]
+const allowedProps: AllowedPropKeys = ['children', 'renderSortLabel']
 
 export type { TableHeadProps, TableHeadStyle }
 export { propTypes, allowedProps }

package/src/Table/Head/styles.ts

@@ -31,8 +31,6 @@ import type { TableHeadStyle } from './props'
  * ---
  * Generates the style object from the theme and provided additional information
  * @param  {Object} componentTheme The theme variable object.
- * @param  {Object} props the props of the component, the style is applied to
- * @param  {Object} state the state of the component, the style is applied to
  * @return {Object} The final style object, which will be used in the component
  */
 const generateStyle = (componentTheme: TableHeadTheme): TableHeadStyle => {