fix(ui-table,ui-codemods): set caption prop to required

BREAKING CHANGE: Table's caption have to be set from now on.

Author: joyenjoyer

docs/contributor-docs/upgrade-guide.md

@@ -74,6 +74,8 @@ The **`<CodeEditor>` component** from the `ui-code-editor` package has been **re
 | `Body`    | `hover`     | is now stored in `TableContext` |
 | `Body`    | `headers`   | is now stored in `TableContext` |
 
+[Table](#Table)'s `caption` prop is now required.
+
 ---
 
 ## API Changes

packages/ui-codemods/lib/__node_tests__/__testfixtures__/warnTableCaptionMissing/noCaption.input.tsx

@@ -0,0 +1,18 @@
+import { Table } from '@instructure/ui-table'
+
+export default function Example() {
+  return (
+    <Table>
+      <thead>
+        <tr>
+          <th>Header</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Data</td>
+        </tr>
+      </tbody>
+    </Table>
+  )
+}

packages/ui-codemods/lib/__node_tests__/__testfixtures__/warnTableCaptionMissing/withCaption.input.tsx

@@ -0,0 +1,18 @@
+import { Table } from '@instructure/ui-table'
+
+export default function Example() {
+  return (
+    <Table caption="My table">
+      <thead>
+        <tr>
+          <th>Header</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Data</td>
+        </tr>
+      </tbody>
+    </Table>
+  )
+}

packages/ui-codemods/lib/__node_tests__/codemods.test.ts

@@ -28,6 +28,9 @@ import removeAsFromInstUISettingsProvider from '../removeAsFromInstUISettingsPro
 import renameCanvasThemesCodemod from '../renameCanvasThemesCodemod'
 import updateCodeEditorImport from '../updateCodeEditorImport'
 import renameGetComputedStyleToGetCSSStyleDeclaration from '../renameGetComputedStyleToGetCSSStyleDeclaration'
+import { printWarning } from '../utils/codemodHelpers'
+import warnTableCaptionMissing from '../warnTableCaptionMissing'
+import { vi, expect } from 'vitest'
 
 describe('test codemods', () => {
   it('test InstUI v10 color codemods', () => {
@@ -49,4 +52,38 @@ describe('test codemods', () => {
   it('test renaming "getComputedStyle" to getCSSStyleDeclaration', () => {
     runTest(renameGetComputedStyleToGetCSSStyleDeclaration)
   })
+
+  it('test Table caption warning codemod', async () => {
+    const fs = await import('fs/promises')
+    const noCaptionInput = await fs.readFile(
+      require.resolve(
+        './__testfixtures__/warnTableCaptionMissing/noCaption.input.tsx'
+      ),
+      'utf-8'
+    )
+    const withCaptionInput = await fs.readFile(
+      require.resolve(
+        './__testfixtures__/warnTableCaptionMissing/withCaption.input.tsx'
+      ),
+      'utf-8'
+    )
+    // Test: should warn if Table is missing caption
+    const spy = vi.spyOn(printWarning, 'call')
+    warnTableCaptionMissing(
+      { source: noCaptionInput, path: 'noCaption.input.tsx' } as any,
+      { jscodeshift: require('jscodeshift') } as any,
+      {}
+    )
+    expect(spy).toHaveBeenCalled()
+    spy.mockClear()
+
+    // Test: should NOT warn if Table has caption
+    warnTableCaptionMissing(
+      { source: withCaptionInput, path: 'withCaption.input.tsx' } as any,
+      { jscodeshift: require('jscodeshift') } as any,
+      {}
+    )
+    expect(spy).not.toHaveBeenCalled()
+    spy.mockRestore()
+  })
 })

packages/ui-codemods/lib/index.ts

@@ -28,12 +28,14 @@ import removeAsFromInstUISettingsProvider from './removeAsFromInstUISettingsProv
 import { renameCanvasThemes } from './renameCanvasThemesCodemod'
 import updateCodeEditorImport from './updateCodeEditorImport'
 import renameGetComputedStyleToGetCSSStyleDeclaration from './renameGetComputedStyleToGetCSSStyleDeclaration'
+import warnTableCaptionMissing from './warnTableCaptionMissing'
 
 export {
   updateV10Breaking,
   instUIv11Codemods,
   removeAsFromInstUISettingsProvider,
   renameCanvasThemes,
   updateCodeEditorImport,
-  renameGetComputedStyleToGetCSSStyleDeclaration
+  renameGetComputedStyleToGetCSSStyleDeclaration,
+  warnTableCaptionMissing
 }

packages/ui-codemods/lib/warnTableCaptionMissing.ts

@@ -0,0 +1,69 @@
+/*
+ * 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 type { FileInfo, API, Options } from 'jscodeshift'
+import {
+  findImport,
+  findElement,
+  findAttribute,
+  printWarning
+} from './utils/codemodHelpers'
+
+const TABLE_IMPORT_PATHS = ['@instructure/ui-table', '@instructure/ui']
+
+export default function warnTableCaptionMissing(
+  file: FileInfo,
+  api: API,
+  options: Options
+) {
+  const j = api.jscodeshift
+  const root = j(file.source)
+  const filePath = file.path
+
+  // Find the local name for Table (could be aliased)
+  const tableName = findImport(j, root, 'Table', TABLE_IMPORT_PATHS)
+  if (!tableName) return file.source
+
+  // Find all <Table> elements
+  const tableElements = findElement(filePath, j, root, tableName)
+
+  tableElements.forEach((path) => {
+    // Check if caption attribute exists
+    const hasCaption =
+      findAttribute(
+        filePath,
+        j,
+        j(path.value.openingElement),
+        'caption'
+      ).size() > 0
+    if (!hasCaption) {
+      printWarning(
+        filePath,
+        path.value.loc?.start.line,
+        `<${tableName}> is missing required 'caption' prop.`
+      )
+    }
+  })
+
+  return file.source
+}

packages/ui-table/src/Table/__tests__/Table.test.tsx

@@ -80,7 +80,8 @@ describe('<Table />', async () => {
 
   it('applies a fixed column layout', async () => {
     await renderTable({
-      layout: 'fixed'
+      layout: 'fixed',
+      caption: 'Test table'
     })
     const table = screen.getByRole('table')
 
@@ -89,7 +90,8 @@ describe('<Table />', async () => {
 
   it('passes hover to table row', async () => {
     renderTable({
-      hover: true
+      hover: true,
+      caption: 'Test table'
     })
     const tableRows = screen.getAllByRole('row')
 
@@ -119,7 +121,8 @@ describe('<Table />', async () => {
 
   it('can render table in stacked layout', async () => {
     renderTable({
-      layout: 'stacked'
+      layout: 'stacked',
+      caption: 'Test table'
     })
     const stackedTable = screen.getByRole('table')
 

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

@@ -44,6 +44,7 @@ import type { TableProps } from './props'
 
 import { allowedProps } from './props'
 import TableContext from './TableContext'
+import { error } from '@instructure/console'
 
 /**
 ---
@@ -110,6 +111,10 @@ class Table extends Component<TableProps> {
     const isStacked = layout === 'stacked'
     const headers = isStacked ? this.getHeaders() : undefined
 
+    if (!caption) {
+      error(false, `[Table] required prop caption is not set.`)
+    }
+
     return (
       <TableContext.Provider
         value={{

packages/ui-table/src/Table/props.ts

@@ -36,7 +36,7 @@ type TableOwnProps = {
    * Provide a screen reader friendly description. Anything passed to this
    * prop will be wrapped by `<ScreenReaderContent>` when it is rendered.
    */
-  caption?: React.ReactNode
+  caption: React.ReactNode
   /**
    * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,
    * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via