@instructure/ui-table 10.2.1-snapshot-3 → 10.2.1-snapshot-11

package/src/Table/README.md

@@ -875,12 +875,17 @@ render(
 
 ### Using Custom Components as Children
 
-In some cases you might want to use custom components in a `Table`, e.g. a HOC for `Table.Row` or `Table.Cell`. This is generally not recommended but sometimes it could be beneficial for codesplitting or writing cleaner code for larger and more complex Tables. In those cases you have to pay attention to always pass down the appropriate props manually.
+In some cases you might want to use custom components in a `Table`, e.g. a HOC for `Table.Row` or `Table.Cell`. This is generally not recommended, but sometimes it could be beneficial for codesplitting or writing cleaner code for larger and more complex Tables.
+
+> Do not replace `Table.Body` and `Table.Head` with custom components
+
+Wrapper HOCs are simple, just return the original component:
 
 ```javascript
 ---
 type: example
 ---
+
 class CustomTableCell extends React.Component {
   render () {
     return (
@@ -944,7 +949,6 @@ class Example extends React.Component {
 
   render() {
     const { layout, hover } = this.state
-
     return (
       <div>
         {this.renderOptions()}
@@ -985,6 +989,299 @@ class Example extends React.Component {
 render(<Example />)
 ```
 
+#### Fully custom components
+
+If you want to use fully custom components you have to pay attention to the following:
+
+- Render them as the appropriate HTML Table tags (`tr`, `th`, ...)
+- Read the `hover` prop from `TableContext` to customize hover behaviour
+- A11y: Row header cells must have the `scope='row'` HTML attribute
+- A11y: Column header cells must have the `scope='col'` and `aria-sort` (if sortable) HTML attribute
+
+Basic fully custom table:
+
+```javascript
+---
+type: example
+---
+
+class CustomTableCell extends React.Component {
+  render() {
+    return <td>{this.props.children}</td>
+  }
+}
+
+class CustomTableRow extends React.Component {
+  static contextType = TableContext
+  state = { isHovered: false }
+
+  toggleHoverOff = () => {
+    this.setState({isHovered: false})
+  }
+  toggleHoverOn = () => {
+    this.setState({isHovered: true})
+  }
+  render() {
+    // super ugly way to change CSS on hover
+    let css = {backgroundColor: 'white'}
+    if (this.context.hover && this.state.isHovered) {
+      css = {backgroundColor: 'SeaGreen'}
+    }
+    return (
+      <tr style={css} onMouseOver={this.toggleHoverOn} onMouseOut={this.toggleHoverOff}>
+        {this.props.children}
+      </tr>
+    )
+  }
+}
+
+class Example extends React.Component {
+  state = {
+    layout: 'auto',
+    hover: false,
+  }
+
+  handleChange = (field, value) => {
+    this.setState({
+      [field]: value,
+    })
+  }
+
+  renderOptions () {
+    const { layout, hover } = this.state
+
+    return (
+      <Flex alignItems="start">
+        <Flex.Item margin="small">
+          <RadioInputGroup
+            name="Layout"
+            description="Layout"
+            value={layout}
+            onChange={(e, value) => this.handleChange('layout', value)}
+          >
+            <RadioInput label="auto" value="auto" />
+            <RadioInput label="fixed" value="fixed" />
+          </RadioInputGroup>
+        </Flex.Item>
+        <Flex.Item margin="small">
+          <Checkbox
+            label="hover"
+            checked={hover}
+            onChange={(e, value) => this.handleChange('hover', !hover)}
+          />
+        </Flex.Item>
+      </Flex>
+    )
+  }
+
+  render() {
+    const { layout, hover } = this.state
+
+    return (
+      <div>
+        {this.renderOptions()}
+        <Table
+          caption='Top rated movies'
+          layout={layout}
+          hover={hover}
+        >
+          <Table.Head>
+            <CustomTableRow>
+              <CustomTableCell scope='col'>Rank</CustomTableCell>
+              <CustomTableCell scope='col'>Title</CustomTableCell>
+              <CustomTableCell scope='col'>Year</CustomTableCell>
+              <CustomTableCell scope='col'>Rating</CustomTableCell>
+            </CustomTableRow>
+          </Table.Head>
+          <Table.Body>
+            <CustomTableRow>
+              <CustomTableCell scope='row'>1</CustomTableCell>
+              <CustomTableCell>The Godfather</CustomTableCell>
+              <CustomTableCell>1972</CustomTableCell>
+              <CustomTableCell>9.2</CustomTableCell>
+            </CustomTableRow>
+            <CustomTableRow>
+              <CustomTableCell scope='row'>2</CustomTableCell>
+              <CustomTableCell>The Godfather: Part II</CustomTableCell>
+              <CustomTableCell>1974</CustomTableCell>
+              <CustomTableCell>9.0</CustomTableCell>
+            </CustomTableRow>
+          </Table.Body>
+        </Table>
+      </div>
+    )
+  }
+}
+
+render(<Example />)
+```
+
+#### Fully custom components with `stacked` layout
+
+This layout for small screens displays the table as a list. To accomplish this the headers are passed down to cells (in `TableContext`), so they can display what column they are rendering.
+In this layout for accessibility not render HTML table tags, just plain DOM elements (e.g. `div`) and use the appropriate ARIA role to signify that it's actually a `Table` (e.g. [`cell`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role), [`row`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/row_role), [`rowheader`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role)).  
+Also you need the following props on the components:
+
+##### Table rows
+
+- It should read the `headers` array from `TableContext` and pass its nth element to its nth child (if they have such prop).
+
+##### The children of the first row in `Table.Head` (`Table.ColHeader` by default)
+
+- If the table is sortable the Table needs `id`, `onRequestSort`, `sortDirection` and `stackedSortByLabel` props to render a `Select` to choose how to sort the `Table` (see the props of `Table.ColHeader` for types)
+
+##### Table cells
+
+- It needs to have an optional `header` prop and should display its value so the user knows which column the cell's value belongs to (you can read whether the table is using `stacked` layout from `TableContext`.
+
+Custom table with `stacked` layout support:
+
+```javascript
+---
+type: example
+---
+
+class CustomTableCell extends React.Component {
+  static contextType = TableContext
+
+  render() {
+    const isStacked = this.context.isStacked
+    if (isStacked) {
+      let headerTxt
+      if (typeof this.props.header === 'function') {
+        headerTxt = React.createElement(this.props.header)
+      } else {
+        headerTxt = this.props.header
+      }
+      return <div role="cell">
+        {headerTxt && headerTxt}
+        {headerTxt && ': '}
+        {this.props.children}
+      </div>
+    }
+    return <td>{this.props.children}</td>
+  }
+}
+
+class CustomTableRow extends React.Component {
+  static contextType = TableContext
+  state = { isHovered: false }
+
+  toggleHoverOff = () => {
+    this.setState({isHovered: false})
+  }
+  toggleHoverOn = () => {
+    this.setState({isHovered: true})
+  }
+  render() {
+    // super ugly way to change CSS on hover
+    let css = {backgroundColor: 'white'}
+    if (this.context.hover && this.state.isHovered) {
+      css = {backgroundColor: 'SeaGreen'}
+    }
+    const headers = this.context.headers
+    const isStacked = this.context.isStacked
+    const Tag = isStacked ? 'div' : 'tr'
+    return (
+      <Tag style={css} role={isStacked ? 'row' : undefined}
+           onMouseOver={this.toggleHoverOn} onMouseOut={this.toggleHoverOff}>
+        {React.Children.toArray(this.props.children)
+          .filter(React.isValidElement)
+          .map((child, index) => {
+            return React.cloneElement(child, {
+              key: child.props.name,
+              // used by `CustomTableCell` to render its column title in `stacked` layout
+              header: headers && headers[index]
+            })
+          })
+        }
+      </Tag>
+    )
+  }
+}
+
+class Example extends React.Component {
+  state = {
+    layout: 'auto',
+    hover: false,
+  }
+
+  handleChange = (field, value) => {
+    this.setState({
+      [field]: value,
+    })
+  }
+
+  renderOptions () {
+    const { layout, hover } = this.state
+
+    return (
+      <Flex alignItems="start">
+        <Flex.Item margin="small">
+          <RadioInputGroup
+            name="customStackedLayout"
+            description="Layout"
+            value={layout}
+            onChange={(e, value) => this.handleChange('layout', value)}
+          >
+            <RadioInput label="auto" value="auto" />
+            <RadioInput label="fixed" value="fixed" />
+            <RadioInput label="stacked" value="stacked" />
+          </RadioInputGroup>
+        </Flex.Item>
+        <Flex.Item margin="small">
+          <Checkbox
+            label="hover"
+            checked={hover}
+            onChange={(e, value) => this.handleChange('hover', !hover)}
+          />
+        </Flex.Item>
+      </Flex>
+    )
+  }
+
+  render() {
+    const { layout, hover } = this.state
+
+    return (
+      <div>
+        {this.renderOptions()}
+        <Table
+          caption='Top rated movies'
+          layout={layout}
+          hover={hover}
+        >
+          <Table.Head>
+            <CustomTableRow>
+              <CustomTableCell scope='col'>Rank</CustomTableCell>
+              <CustomTableCell scope='col'>Title</CustomTableCell>
+              <CustomTableCell scope='col'>Year</CustomTableCell>
+              <CustomTableCell scope='col'>Rating</CustomTableCell>
+            </CustomTableRow>
+          </Table.Head>
+          <Table.Body>
+            <CustomTableRow>
+              <CustomTableCell scope='row'>1</CustomTableCell>
+              <CustomTableCell>The Godfather</CustomTableCell>
+              <CustomTableCell>1972</CustomTableCell>
+              <CustomTableCell>9.2</CustomTableCell>
+            </CustomTableRow>
+            <CustomTableRow>
+              <CustomTableCell scope='row'>2</CustomTableCell>
+              <CustomTableCell>The Godfather: Part II</CustomTableCell>
+              <CustomTableCell>1974</CustomTableCell>
+              <CustomTableCell>9.0</CustomTableCell>
+            </CustomTableRow>
+          </Table.Body>
+        </Table>
+      </div>
+    )
+  }
+}
+
+render(<Example />)
+```
+
 ### Guidelines
 
 ```js

package/src/Table/Row/index.tsx

@@ -23,7 +23,7 @@
  */
 
 /** @jsx jsx */
-import { Component, Children } from 'react'
+import { Component, Children, ContextType, isValidElement } from 'react'
 
 import { omitProps, safeCloneElement } from '@instructure/ui-react-utils'
 import { View } from '@instructure/ui-view'
@@ -35,6 +35,7 @@ import generateComponentTheme from './theme'
 
 import type { TableRowProps } from './props'
 import { allowedProps, propTypes } from './props'
+import TableContext from '../TableContext'
 
 /**
 ---
@@ -45,7 +46,8 @@ id: Table.Row
 @withStyle(generateStyle, generateComponentTheme)
 class Row extends Component<TableRowProps> {
   static readonly componentId = 'Table.Row'
-
+  static contextType = TableContext
+  declare context: ContextType<typeof TableContext>
   static allowedProps = allowedProps
   static propTypes = propTypes
 
@@ -54,15 +56,23 @@ class Row extends Component<TableRowProps> {
   }
 
   componentDidMount() {
-    this.props.makeStyles?.()
+    this.props.makeStyles?.({
+      isStacked: this.context.isStacked,
+      hover: this.context.hover
+    })
   }
 
   componentDidUpdate() {
-    this.props.makeStyles?.()
+    this.props.makeStyles?.({
+      isStacked: this.context.isStacked,
+      hover: this.context.hover
+    })
   }
 
   render() {
-    const { children, styles, isStacked, headers } = this.props
+    const { children, styles } = this.props
+    const isStacked = this.context.isStacked
+    const headers = this.context.headers
 
     return (
       <View
@@ -73,12 +83,18 @@ class Row extends Component<TableRowProps> {
       >
         {Children.toArray(children)
           .filter(Boolean)
-          .map((child: any, index) => {
-            return safeCloneElement(child, {
-              key: child.props.name,
-              isStacked,
-              header: headers && headers[index]
-            })
+          .map((child, index) => {
+            if (isValidElement(child)) {
+              return safeCloneElement(child, {
+                key: child.props.name,
+                // Sent down for compatibility with custom components
+                // TODO DEPRECATED, remove in v11
+                isStacked,
+                // used by `Cell` to render its column title in `stacked` layout
+                header: headers && headers[index]
+              })
+            }
+            return child
           })}
       </View>
     )

package/src/Table/Row/props.ts

@@ -25,8 +25,6 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 
-import type { TableCellProps } from '../Cell/props'
-
 import type {
   OtherHTMLAttributes,
   PropValidators,
@@ -35,13 +33,13 @@ import type {
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
 
 type TableRowOwnProps = {
-  hover?: boolean
-  isStacked?: boolean
-  headers?: TableCellProps['header'][]
   /**
-   * `Table.ColHeader`, `Table.RowHeader` or `Table.Cell`
+   * A row's children should be table cells. Its children should have the
+   * `header` prop to render the column header in `stacked` layout
+   *
+   * By default `Table.ColHeader` or `Table.RowHeader` or `Table.Cell`
    */
-  children?: React.ReactNode
+  children?: React.ReactElement | React.ReactElement[]
 }
 
 type PropKeys = keyof TableRowOwnProps
@@ -55,20 +53,10 @@ type TableRowProps = TableRowOwnProps &
 type TableRowStyle = ComponentStyle<'row'>
 
 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 { TableRowProps, TableRowStyle }
 export { propTypes, allowedProps }

package/src/Table/Row/styles.ts

@@ -32,15 +32,14 @@ import type { TableRowProps, TableRowStyle } 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
+ * @param  {Object} extraArgs 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: TableRowTheme,
-  props: TableRowProps
+  _props: TableRowProps,
+  extraArgs: { isStacked: boolean; hover: boolean }
 ): TableRowStyle => {
-  const { hover, isStacked } = props
-
   return {
     row: {
       label: 'row',
@@ -54,7 +53,7 @@ const generateStyle = (
       borderBottomWidth: '0.0625rem',
       borderBottomColor: componentTheme.borderColor,
 
-      ...(hover && {
+      ...(extraArgs.hover && {
         borderLeft: '0.1875rem solid transparent',
         borderRight: '0.1875rem solid transparent',
 
@@ -64,7 +63,7 @@ const generateStyle = (
         }
       }),
 
-      ...(isStacked && { padding: componentTheme.padding })
+      ...(extraArgs.isStacked && { padding: componentTheme.padding })
     }
   }
 }

package/src/Table/RowHeader/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 { TableRowHeaderProps } from './props'
 import { allowedProps, propTypes } from './props'
+import TableContext from '../TableContext'
 
 /**
 ---
@@ -44,7 +45,8 @@ id: Table.RowHeader
 @withStyle(generateStyle, generateComponentTheme)
 class RowHeader extends Component<TableRowHeaderProps> {
   static readonly componentId = 'Table.RowHeader'
-
+  static contextType = TableContext
+  declare context: ContextType<typeof TableContext>
   static allowedProps = allowedProps
   static propTypes = propTypes
 
@@ -62,8 +64,8 @@ class RowHeader extends Component<TableRowHeaderProps> {
   }
 
   render() {
-    const { children, isStacked, styles } = this.props
-
+    const { children, styles } = this.props
+    const isStacked = this.context.isStacked
     return (
       <View
         {...View.omitViewProps(

package/src/Table/RowHeader/props.ts

@@ -33,7 +33,6 @@ import type {
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
 
 type TableRowHeaderOwnProps = {
-  isStacked?: boolean
   /**
    * Control the text alignment in row header
    */
@@ -53,11 +52,10 @@ type TableRowHeaderStyle = ComponentStyle<'rowHeader'>
 
 const propTypes: PropValidators<PropKeys> = {
   children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
-  isStacked: PropTypes.bool,
   textAlign: PropTypes.oneOf(['start', 'center', 'end'])
 }
 
-const allowedProps: AllowedPropKeys = ['children', 'isStacked', 'textAlign']
+const allowedProps: AllowedPropKeys = ['children', 'textAlign']
 
 export type { TableRowHeaderProps, TableRowHeaderStyle }
 export { propTypes, allowedProps }

package/src/Table/TableContext.ts

@@ -0,0 +1,54 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { createContext } from 'react'
+import { Renderable } from '@instructure/shared-types'
+
+type TableContextType = {
+  /**
+   * If `true` the table gets rendered in one column to be more readable on
+   * narrow screens.
+   */
+  isStacked: boolean
+  /**
+   * Highlight each row on hover.
+   */
+  hover: boolean
+  /**
+   * Contents of the first row of cells. Has value if `isStacked` is `true`.
+   */
+  headers?: Renderable[]
+}
+
+/**
+ * React context created by the `Table` component to hold its data
+ */
+const TableContext = createContext<TableContextType>({
+  isStacked: false,
+  hover: false
+})
+
+export default TableContext
+export { TableContext }
+export type { TableContextType }