feat(ui-tabs): add roving tabindex and manual activation mode

packages/ui-tabs/package.json

@@ -29,7 +29,6 @@
     "@instructure/emotion": "workspace:*",
     "@instructure/shared-types": "workspace:*",
     "@instructure/ui-dom-utils": "workspace:*",
-    "@instructure/ui-focusable": "workspace:*",
     "@instructure/ui-i18n": "workspace:*",
     "@instructure/ui-motion": "workspace:*",
     "@instructure/ui-react-utils": "workspace:*",

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

@@ -59,7 +59,7 @@ describe('<Tabs.Tab />', () => {
     )
     const tab = page.getByRole('tab').element()
 
-    expect(tab).not.toHaveAttribute('aria-selected')
+    expect(tab).toHaveAttribute('aria-selected', 'false')
     expect(tab).not.toHaveAttribute('aria-disabled')
   })
 
@@ -96,15 +96,15 @@ describe('<Tabs.Tab />', () => {
     expect(tab).toHaveAttribute('tabindex', '0')
   })
 
-  it('should not set the tabindex when not selected', async () => {
+  it('should set the tabindex to -1 when not selected', async () => {
     await render(
       <Tab id="foo" index={0} controls="foo-panel">
         Tab Label
       </Tab>
     )
     const tab = page.getByRole('tab').element()
 
-    expect(tab).not.toHaveAttribute('tabindex')
+    expect(tab).toHaveAttribute('tabindex', '-1')
   })
 
   it('should remove the tabindex attribute when disabled', async () => {

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

@@ -0,0 +1,220 @@
+/*
+ * 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 { useState } from 'react'
+import { render } from 'vitest-browser-react'
+import { page, userEvent } from 'vitest/browser'
+import { describe, it, expect, vi } from 'vitest'
+
+import { Tabs as TabsLatest } from '@instructure/ui-tabs/latest'
+import { Tabs as TabsV1 } from '@instructure/ui-tabs/v11_6'
+
+type TabsComponent = typeof TabsLatest
+
+const tabEl = (name: string) => page.getByText(name).element() as HTMLElement
+
+// v1 and v2 differ only in theming, so both have to pass every assertion here.
+function describeKeyboard(name: string, Tabs: TabsComponent) {
+  const Example = (props: {
+    activationMode?: 'auto' | 'manual'
+    onChange?: (index: number) => void
+  }) => {
+    const [selectedIndex, setSelectedIndex] = useState(0)
+    return (
+      <Tabs
+        activationMode={props.activationMode}
+        onRequestTabChange={(_event, { index }) => {
+          setSelectedIndex(index)
+          props.onChange?.(index)
+        }}
+      >
+        <Tabs.Panel
+          renderTitle="First Tab"
+          id="one"
+          isSelected={selectedIndex === 0}
+        >
+          Tab 1 content
+        </Tabs.Panel>
+        <Tabs.Panel
+          renderTitle="Second Tab"
+          id="two"
+          isSelected={selectedIndex === 1}
+        >
+          Tab 2 content
+        </Tabs.Panel>
+        <Tabs.Panel renderTitle="Disabled Tab" id="three" isDisabled>
+          Tab 3 content
+        </Tabs.Panel>
+        <Tabs.Panel
+          renderTitle="Fourth Tab"
+          id="four"
+          isSelected={selectedIndex === 3}
+        >
+          Tab 4 content
+        </Tabs.Panel>
+      </Tabs>
+    )
+  }
+
+  describe(`<Tabs /> ${name} keyboard navigation`, () => {
+    it('moves focus onto the newly selected tab on each arrow press', async () => {
+      await render(<Example />)
+
+      tabEl('First Tab').focus()
+
+      await userEvent.keyboard('{ArrowRight}')
+      await vi.waitFor(() => {
+        expect(document.activeElement).toBe(tabEl('Second Tab'))
+      })
+
+      // skips the disabled tab
+      await userEvent.keyboard('{ArrowRight}')
+      await vi.waitFor(() => {
+        expect(document.activeElement).toBe(tabEl('Fourth Tab'))
+      })
+
+      await userEvent.keyboard('{ArrowLeft}')
+      await vi.waitFor(() => {
+        expect(document.activeElement).toBe(tabEl('Second Tab'))
+      })
+    })
+
+    it('gives unselected tabs tabindex="-1" so they can take focus', async () => {
+      await render(<Example />)
+
+      const second = tabEl('Second Tab')
+
+      expect(tabEl('First Tab')).toHaveAttribute('tabindex', '0')
+      expect(second).toHaveAttribute('tabindex', '-1')
+
+      second.focus()
+      expect(document.activeElement).toBe(second)
+    })
+
+    it('reports aria-selected="false" on unselected tabs', async () => {
+      await render(<Example />)
+
+      expect(tabEl('First Tab')).toHaveAttribute('aria-selected', 'true')
+      expect(tabEl('Second Tab')).toHaveAttribute('aria-selected', 'false')
+    })
+
+    it('marks the tablist as horizontally oriented', async () => {
+      await render(<Example />)
+
+      expect(page.getByRole('tablist').element()).toHaveAttribute(
+        'aria-orientation',
+        'horizontal'
+      )
+    })
+
+    it('selects the first and last enabled tab with Home and End', async () => {
+      const onChange = vi.fn()
+      await render(<Example onChange={onChange} />)
+
+      tabEl('First Tab').focus()
+
+      await userEvent.keyboard('{End}')
+      await vi.waitFor(() => {
+        expect(onChange).toHaveBeenLastCalledWith(3)
+        expect(document.activeElement).toBe(tabEl('Fourth Tab'))
+      })
+
+      await userEvent.keyboard('{Home}')
+      await vi.waitFor(() => {
+        expect(onChange).toHaveBeenLastCalledWith(0)
+        expect(document.activeElement).toBe(tabEl('First Tab'))
+      })
+    })
+
+    it('does not warn about Focusable while navigating', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      await render(<Example />)
+
+      tabEl('First Tab').focus()
+      await userEvent.keyboard('{ArrowRight}')
+      await vi.waitFor(() => {
+        expect(document.activeElement).toBe(tabEl('Second Tab'))
+      })
+
+      const focusableWarnings = warnSpy.mock.calls.filter((args) =>
+        /\[Focusable\]/.test(String(args[0]))
+      )
+      warnSpy.mockRestore()
+
+      expect(focusableWarnings).toEqual([])
+    })
+  })
+
+  describe(`<Tabs /> ${name} manual activation`, () => {
+    it('moves focus without selecting when arrowing', async () => {
+      const onChange = vi.fn()
+      await render(<Example activationMode="manual" onChange={onChange} />)
+
+      tabEl('First Tab').focus()
+      await userEvent.keyboard('{ArrowRight}')
+
+      await vi.waitFor(() => {
+        expect(document.activeElement).toBe(tabEl('Second Tab'))
+      })
+      expect(onChange).not.toHaveBeenCalled()
+      expect(tabEl('First Tab')).toHaveAttribute('aria-selected', 'true')
+      expect(tabEl('Second Tab')).toHaveAttribute('aria-selected', 'false')
+    })
+
+    it('keeps the roving tabindex on the focused tab, not the selected one', async () => {
+      await render(<Example activationMode="manual" />)
+
+      tabEl('First Tab').focus()
+      await userEvent.keyboard('{ArrowRight}')
+
+      await vi.waitFor(() => {
+        expect(tabEl('Second Tab')).toHaveAttribute('tabindex', '0')
+        expect(tabEl('First Tab')).toHaveAttribute('tabindex', '-1')
+      })
+    })
+
+    for (const key of ['{Enter}', '{ }'] as const) {
+      it(`selects the focused tab on ${key}`, async () => {
+        const onChange = vi.fn()
+        await render(<Example activationMode="manual" onChange={onChange} />)
+
+        tabEl('First Tab').focus()
+        await userEvent.keyboard('{ArrowRight}')
+        await vi.waitFor(() => {
+          expect(document.activeElement).toBe(tabEl('Second Tab'))
+        })
+        expect(onChange).not.toHaveBeenCalled()
+
+        await userEvent.keyboard(key)
+        await vi.waitFor(() => {
+          expect(onChange).toHaveBeenCalledWith(1)
+          expect(tabEl('Second Tab')).toHaveAttribute('aria-selected', 'true')
+        })
+      })
+    }
+  })
+}
+
+describeKeyboard('v2 (latest)', TabsLatest)
+describeKeyboard('v1 (v11_6)', TabsV1 as unknown as TabsComponent)

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

@@ -2,7 +2,7 @@
 describes: Tabs
 ---
 
-`<Tabs />` is an accessible tabbed navigation component. Use the TAB key to focus the component and arrow keys to navigate between panels of content. To set a default panel that should be selected on initial render, set the `selected` prop on that `<Tabs.Panel>`.
+`<Tabs />` is an accessible tabbed navigation component. Use the TAB key to focus the component and arrow keys to navigate between panels of content. Home and End jump to the first and last tab. By default a tab is selected as soon as it is focused; see [Manual activation](#Tabs/#Manual-activation) to require a key press instead. To set a default panel that should be selected on initial render, set the `selected` prop on that `<Tabs.Panel>`.
 
 ```js
 ---
@@ -533,6 +533,47 @@ const Example = () => {
 render(<Example />)
 ```
 
+### Manual activation
+
+By default (`activationMode="auto"`) a tab is selected the moment an arrow key
+focuses it. Set `activationMode="manual"` to separate the two: arrow keys, Home,
+and End only move focus, and Enter or Space selects the focused tab.
+
+Use manual activation when a panel is slow to load, so a keyboard user can scan
+the tab strip without triggering every panel on the way. It also matters for
+VoiceOver, which keeps the arrow keys for its own cursor and so never delivers
+them to the page — Enter and Space are passed through.
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  return (
+    <Tabs
+      activationMode="manual"
+      margin="large auto"
+      padding="medium"
+      onRequestTabChange={(event, { index }) => setSelectedIndex(index)}
+    >
+      <Tabs.Panel id="manualA" renderTitle="First Tab" isSelected={selectedIndex === 0}>
+        Arrow to another tab, then press Enter or Space to open it.
+      </Tabs.Panel>
+      <Tabs.Panel id="manualB" renderTitle="Second Tab" isSelected={selectedIndex === 1}>
+        Second panel
+      </Tabs.Panel>
+      <Tabs.Panel id="manualC" renderTitle="Third Tab" isSelected={selectedIndex === 2}>
+        Third panel
+      </Tabs.Panel>
+    </Tabs>
+  )
+}
+
+render(<Example />)
+```
+
 ### Guidelines
 
 ```js

packages/ui-tabs/src/Tabs/v1/Tab/index.tsx

@@ -93,9 +93,11 @@ class Tab extends Component<TabsTabProps> {
       variant,
       isSelected,
       isDisabled,
+      isFocusable,
       controls,
       children,
       styles,
+      elementRef,
       ...props
     } = this.props
 
@@ -105,13 +107,14 @@ class Tab extends Component<TabsTabProps> {
         as="div"
         role="tab"
         id={id}
+        elementRef={elementRef}
         onClick={this.handleClick}
         onKeyDown={this.handleKeyDown}
         css={styles?.tab}
-        aria-selected={isSelected ? 'true' : undefined}
+        aria-selected={isSelected ? 'true' : 'false'}
         aria-disabled={isDisabled ? 'true' : undefined}
         aria-controls={controls}
-        tabIndex={isSelected && !isDisabled ? 0 : undefined}
+        tabIndex={isDisabled ? undefined : isFocusable ?? isSelected ? 0 : -1}
         position="relative"
         focusPosition="inset"
       >

packages/ui-tabs/src/Tabs/v1/Tab/props.ts

@@ -38,6 +38,11 @@ type TabsTabOwnProps = {
   controls: string
   isDisabled?: boolean
   isSelected?: boolean
+  /**
+   * Whether this tab holds the tablist's roving tabindex. Exactly one tab in a
+   * tablist should have it. Defaults to `isSelected`.
+   */
+  isFocusable?: boolean
   onClick?: (
     event: React.MouseEvent<ViewOwnProps>,
     tabData: { index: number; id: string }
@@ -51,6 +56,10 @@ type TabsTabOwnProps = {
    * Whether tabOverflow prop in Tabs is set to 'scroll'.
    */
   isOverflowScroll?: boolean
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
 }
 
 type PropKeys = keyof TabsTabOwnProps
@@ -70,10 +79,12 @@ const allowedProps: AllowedPropKeys = [
   'controls',
   'isDisabled',
   'isSelected',
+  'isFocusable',
   'onClick',
   'onKeyDown',
   'children',
-  'isOverflowScroll'
+  'isOverflowScroll',
+  'elementRef'
 ]
 
 export type { TabsTabProps, TabsTabStyle }