feat(ui-tabs): TabPanel shouldn't always recieve focus

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

@@ -49,4 +49,26 @@ describe('<Tabs.Panel />', () => {
 
     expect(tabPanel).toHaveAttribute('role', 'tabpanel')
   })
+
+  it('should not 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).not.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')
+  })
 })

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

@@ -98,6 +98,7 @@ class Panel extends Component<TabsPanelProps> {
       styles,
       active,
       unmountOnExit,
+      tabIndex,
       ...props
     } = this.props
 
@@ -106,10 +107,10 @@ class Panel extends Component<TabsPanelProps> {
         {...passthroughProps(props)}
         css={styles?.panel}
         role="tabpanel"
-        tabIndex={0}
         id={id}
         aria-labelledby={labelledBy}
         aria-hidden={this.isHidden ? 'true' : undefined}
+        tabIndex={this.isHidden ? undefined : tabIndex}
         ref={this.handleRef}
       >
         <Transition

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

@@ -62,6 +62,11 @@ 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. Set to 0 for text-only panels to make them
+   * accessible to keyboard and screen reader users.
+   */
+  tabIndex?: number
 }
 
 type PropKeys = keyof TabsPanelOwnProps
@@ -87,7 +92,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"
@@ -31,21 +32,35 @@ const Example = () => {
         <Button>Focus Me</Button>
       </Tabs.Panel>
       <Tabs.Panel id="tabB" renderTitle="Disabled Tab" isDisabled>
-        {lorem.paragraphs()}
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod
+        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
+        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+        commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
+        velit esse cillum dolore eu fugiat nulla pariatur.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabC"
         renderTitle="Tab C"
         isSelected={selectedIndex === 2}
+        tabIndex={0}
       >
-        {lorem.paragraphs()}
+        Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+        accusantium doloremque laudantium. Totam rem aperiam, eaque ipsa quae ab
+        illo inventore veritatis et quasi architecto beatae vitae dicta sunt
+        explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut
+        odit aut fugit, sed quia consequuntur magni dolores.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabD"
         renderTitle="Tab D"
         isSelected={selectedIndex === 3}
+        tabIndex={0}
       >
-        {lorem.paragraphs()}
+        At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis
+        praesentium voluptatum deleniti atque corrupti. Quos dolores et quas
+        molestias excepturi sint occaecati cupiditate non provident, similique
+        sunt in culpa. Qui officia deserunt mollitia animi, id est laborum et
+        dolorum fuga.
       </Tabs.Panel>
     </Tabs>
   )
@@ -74,17 +89,29 @@ const Example = () => {
       minHeight="10rem"
       maxHeight="10rem"
     >
-      <Tabs.Panel renderTitle="First Tab" isSelected={selectedIndex === 0}>
+      <Tabs.Panel renderTitle="First Tab" isSelected={selectedIndex === 0} tabIndex={0}>
         Hello World
       </Tabs.Panel>
       <Tabs.Panel renderTitle="Disabled Tab" isDisabled>
-        {lorem.paragraphs()}
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod
+        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
+        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+        commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
+        velit esse cillum dolore eu fugiat nulla pariatur.
       </Tabs.Panel>
-      <Tabs.Panel renderTitle="Third Tab" isSelected={selectedIndex === 2}>
-        {lorem.paragraphs()}
+      <Tabs.Panel renderTitle="Third Tab" isSelected={selectedIndex === 2} tabIndex={0}>
+        Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+        accusantium doloremque laudantium. Totam rem aperiam, eaque ipsa quae ab
+        illo inventore veritatis et quasi architecto beatae vitae dicta sunt
+        explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut
+        odit aut fugit, sed quia consequuntur magni dolores.
       </Tabs.Panel>
-      <Tabs.Panel renderTitle="Fourth Tab" isSelected={selectedIndex === 3}>
-        {lorem.paragraphs()}
+      <Tabs.Panel renderTitle="Fourth Tab" isSelected={selectedIndex === 3} tabIndex={0}>
+        At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis
+        praesentium voluptatum deleniti atque corrupti. Quos dolores et quas
+        molestias excepturi sint occaecati cupiditate non provident, similique
+        sunt in culpa. Qui officia deserunt mollitia animi, id est laborum et
+        dolorum fuga.
       </Tabs.Panel>
     </Tabs>
   )
@@ -122,50 +149,57 @@ const Example = () => {
         id="tabA"
         renderTitle="Tab A"
         isSelected={selectedIndex === 0}
+        tabIndex={0}
       >
-        {lorem.sentence()}
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabB"
         renderTitle="Tab B"
         isSelected={selectedIndex === 1}
+        tabIndex={0}
       >
-        {lorem.sentence()}
+        Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabC"
         renderTitle="Tab C"
         isSelected={selectedIndex === 2}
+        tabIndex={0}
       >
-        {lorem.sentence()}
+        Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabD"
         renderTitle="Tab D"
         isSelected={selectedIndex === 3}
+        tabIndex={0}
       >
-        {lorem.sentence()}
+        Duis aute irure dolor in reprehenderit in voluptate velit esse.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabE"
         renderTitle="Tab E"
         isSelected={selectedIndex === 4}
+        tabIndex={0}
       >
-        {lorem.sentence()}
+        Excepteur sint occaecat cupidatat non proident, sunt in culpa.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabF"
         renderTitle="Tab F"
         isSelected={selectedIndex === 5}
+        tabIndex={0}
       >
-        {lorem.sentence()}
+        Sed ut perspiciatis unde omnis iste natus error sit voluptatem.
       </Tabs.Panel>
       <Tabs.Panel
         id="tabG"
         renderTitle="Tab G"
         isSelected={selectedIndex === 6}
+        tabIndex={0}
       >
-        {lorem.sentence()}
+        Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit.
       </Tabs.Panel>
     </Tabs>
   )
@@ -244,6 +278,7 @@ const Example = () => {
         >
           <Tabs.Panel
             id="tabA"
+            tabIndex={-1}
             renderTitle="Tab A"
             textAlign="center"
             padding="large"
@@ -252,21 +287,36 @@ const Example = () => {
             <Button>Focus Me</Button>
           </Tabs.Panel>
           <Tabs.Panel id="tabB" renderTitle="Disabled Tab" isDisabled>
-            {lorem.paragraphs()}
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
+            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+            ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+            aliquip ex ea commodo consequat. Duis aute irure dolor in
+            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+            pariatur.
           </Tabs.Panel>
           <Tabs.Panel
             id="tabC"
             renderTitle="Tab C"
             isSelected={selectedIndex === 2}
+            tabIndex={0}
           >
-            {lorem.paragraphs()}
+            Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+            accusantium doloremque laudantium. Totam rem aperiam, eaque ipsa quae
+            ab illo inventore veritatis et quasi architecto beatae vitae dicta
+            sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit
+            aspernatur aut odit aut fugit, sed quia consequuntur magni dolores.
           </Tabs.Panel>
           <Tabs.Panel
             id="tabD"
             renderTitle="Tab D"
             isSelected={selectedIndex === 3}
+            tabIndex={0}
           >
-            {lorem.paragraphs()}
+            At vero eos et accusamus et iusto odio dignissimos ducimus qui
+            blanditiis praesentium voluptatum deleniti atque corrupti. Quos
+            dolores et quas molestias excepturi sint occaecati cupiditate non
+            provident, similique sunt in culpa. Qui officia deserunt mollitia
+            animi, id est laborum et dolorum fuga.
           </Tabs.Panel>
         </Tabs>
       </View>
@@ -299,7 +349,14 @@ const Outlet = () => {
         {show ? 'Hello Developer' : 'Simulating network call...'}
       </Heading>
       {show ? (
-        lorem.paragraphs()
+        <div>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
+          eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
+          minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+          aliquip ex ea commodo consequat. Duis aute irure dolor in
+          reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+          pariatur.
+        </div>
       ) : (
         <Spinner renderTitle="Loading" size="medium" />
       )}
@@ -327,6 +384,7 @@ const Example = () => {
         padding="large"
         isSelected={selectedIndex === 0}
         active
+        tabIndex={0}
       >
         <Outlet />
       </Tabs.Panel>
@@ -387,6 +445,7 @@ const Example = () => {
     >
       <Tabs.Panel
         id="tabA"
+        tabIndex={-1}
         renderTitle="I will persist"
         textAlign="center"
         padding="large"
@@ -397,6 +456,7 @@ const Example = () => {
       </Tabs.Panel>
       <Tabs.Panel
         id="tabB"
+        tabIndex={-1}
         renderTitle="I will unmount"
         isSelected={selectedIndex === 1}
         textAlign="center"
@@ -408,13 +468,15 @@ const Example = () => {
         id="tabC"
         renderTitle="Tab C"
         isSelected={selectedIndex === 2}
+        tabIndex={0}
       >
         Tab C
       </Tabs.Panel>
       <Tabs.Panel
         id="tabD"
         renderTitle="Tab D"
         isSelected={selectedIndex === 3}
+        tabIndex={0}
       >
         Tab D
       </Tabs.Panel>
@@ -425,6 +487,52 @@ const Example = () => {
 render(<Example />)
 ```
 
+### Managing focus with tabIndex
+
+**Best practice:** For text-only panels, set `tabIndex={0}` to include the panel in the keyboard tab sequence—this ensures screen reader users can navigate to and read the content. For panels containing interactive elements (buttons, inputs, links), leave `tabIndex` unset so keyboard users tab directly to the controls without stopping on the panel container first.
+
+```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