feat(ui-tabs): add tabIndex prop to the Panel for WCAG-compliant focus control (defaults to 0 for backward compatibility)

Author: git-nandor

packages/ui-tabs/src/Tabs/Panel/__tests__/Panel.test.tsx

@@ -49,4 +49,37 @@ describe('<Tabs.Panel />', () => {
 
     expect(tabPanel).toHaveAttribute('role', 'tabpanel')
   })
+
+  it('should have tabIndex 0 by default', async () => {
+    const { container } = render(
+      <Panel isSelected renderTitle="Panel Title">
+        Panel contents
+      </Panel>
+    )
+    const tabPanel = container.querySelector('[role="tabpanel"]')
+
+    expect(tabPanel).toHaveAttribute('tabIndex', '0')
+  })
+
+  it('should allow custom tabIndex', async () => {
+    const { container } = render(
+      <Panel isSelected renderTitle="Panel Title" tabIndex={-1}>
+        Panel contents
+      </Panel>
+    )
+    const tabPanel = container.querySelector('[role="tabpanel"]')
+
+    expect(tabPanel).toHaveAttribute('tabIndex', '-1')
+  })
+
+  it('should allow tabIndex to be null to omit the attribute', async () => {
+    const { container } = render(
+      <Panel isSelected renderTitle="Panel Title" tabIndex={null}>
+        Panel contents
+      </Panel>
+    )
+    const tabPanel = container.querySelector('[role="tabpanel"]')
+
+    expect(tabPanel).not.toHaveAttribute('tabIndex')
+  })
 })

packages/ui-tabs/src/Tabs/Panel/index.tsx

@@ -98,15 +98,18 @@ class Panel extends Component<TabsPanelProps> {
       styles,
       active,
       unmountOnExit,
+      tabIndex,
       ...props
     } = this.props
 
+    const shouldSetTabIndex = tabIndex !== undefined ? tabIndex : 0
+
     return (
       <div
         {...passthroughProps(props)}
         css={styles?.panel}
         role="tabpanel"
-        tabIndex={0}
+        {...(shouldSetTabIndex !== null && { tabIndex: shouldSetTabIndex })}
         id={id}
         aria-labelledby={labelledBy}
         aria-hidden={this.isHidden ? 'true' : undefined}

packages/ui-tabs/src/Tabs/Panel/props.ts

@@ -62,6 +62,13 @@ type TabsPanelOwnProps = {
    * When set to false, the tabPanel only will be hidden, but not dismounted when not active
    */
   unmountOnExit?: boolean
+  /**
+   * The tabIndex of the tabpanel element. According to WCAG guidelines, this should only be
+   * set to 0 when the panel doesn't contain any focusable elements. If the panel contains
+   * focusable elements (like buttons, inputs, etc.), this should be set to -1 or null to
+   * omit the attribute entirely. Defaults to 0 for backwards compatibility.
+   */
+  tabIndex?: number | null
 }
 
 type PropKeys = keyof TabsPanelOwnProps
@@ -87,7 +94,8 @@ const allowedProps: AllowedPropKeys = [
   'textAlign',
   'elementRef',
   'active',
-  'unmountOnExit'
+  'unmountOnExit',
+  'tabIndex'
 ]
 
 export type { TabsPanelProps, TabsPanelStyle }

packages/ui-tabs/src/Tabs/README.md

@@ -23,6 +23,7 @@ const Example = () => {
     >
       <Tabs.Panel
         id="tabA"
+        tabIndex={-1}
         renderTitle="Tab A"
         textAlign="center"
         padding="large"
@@ -244,6 +245,7 @@ const Example = () => {
         >
           <Tabs.Panel
             id="tabA"
+            tabIndex={-1}
             renderTitle="Tab A"
             textAlign="center"
             padding="large"
@@ -387,6 +389,7 @@ const Example = () => {
     >
       <Tabs.Panel
         id="tabA"
+        tabIndex={-1}
         renderTitle="I will persist"
         textAlign="center"
         padding="large"
@@ -397,6 +400,7 @@ const Example = () => {
       </Tabs.Panel>
       <Tabs.Panel
         id="tabB"
+        tabIndex={-1}
         renderTitle="I will unmount"
         isSelected={selectedIndex === 1}
         textAlign="center"
@@ -425,6 +429,52 @@ const Example = () => {
 render(<Example />)
 ```
 
+### Managing focus with tabIndex
+
+According to WCAG guidelines, the `tabindex="0"` attribute should only be set on a tabpanel when it doesn't contain any focusable elements. If your panel contains focusable elements (like buttons, inputs, or links), you should set `tabIndex={-1}` to remove the panel from the tab order, or `tabIndex={null}` to omit the attribute entirely.
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  const handleTabChange = (event, { index }) => {
+    setSelectedIndex(index)
+  }
+
+  return (
+    <Tabs
+      margin="large auto"
+      padding="medium"
+      onRequestTabChange={handleTabChange}
+    >
+      <Tabs.Panel
+        id="tabA"
+        renderTitle="Panel with button"
+        textAlign="center"
+        padding="large"
+        isSelected={selectedIndex === 0}
+        tabIndex={-1}
+      >
+        <Button>Focus Me First</Button>
+      </Tabs.Panel>
+      <Tabs.Panel
+        id="tabB"
+        renderTitle="Panel with text only"
+        isSelected={selectedIndex === 1}
+        tabIndex={0}
+      >
+        This panel only contains text, so tabIndex is set to 0 to include it in the tab sequence.
+      </Tabs.Panel>
+    </Tabs>
+  )
+}
+
+render(<Example />)
+```
+
 ### Guidelines
 
 ```js