@instructure/ui-tabs 11.7.10 → 11.7.11-snapshot-4

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.7.11-snapshot-4](https://github.com/instructure/instructure-ui/compare/v11.7.10...v11.7.11-snapshot-4) (2026-10-22)
+
+### Features
+
+* **ui-tabs:** add roving tabindex and manual activation mode ([#2723](https://github.com/instructure/instructure-ui/issues/2723)) ([bc4bbdc](https://github.com/instructure/instructure-ui/commit/bc4bbdc3def4f353f8dc7b5e6ef672625e9efb1b))
+
+
 ## [11.7.10](https://github.com/instructure/instructure-ui/compare/v11.7.8...v11.7.10) (2026-10-14)
 
 **Note:** Version bump only for package @instructure/ui-tabs

package/es/Tabs/v2/Tab/index.js

@@ -86,12 +86,30 @@ let Tab = (_dec = withStyleNew(generateStyle), _dec(_class = class Tab extends C
       });
     }
   };
+  handleFocus = event => {
+    const {
+      onFocus,
+      index,
+      id,
+      isDisabled
+    } = this.props;
+    if (isDisabled) {
+      return;
+    }
+    if (typeof onFocus === 'function') {
+      onFocus(event, {
+        index,
+        id
+      });
+    }
+  };
   render() {
     const {
       id,
       variant,
       isSelected,
       isDisabled,
+      isTabbable = isSelected,
       controls,
       children,
       styles,
@@ -104,11 +122,12 @@ let Tab = (_dec = withStyleNew(generateStyle), _dec(_class = class Tab extends C
       id: id,
       onClick: this.handleClick,
       onKeyDown: this.handleKeyDown,
+      onFocus: this.handleFocus,
       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 : isTabbable ? 0 : -1,
       position: "relative",
       focusPosition: "offset",
       children: callRenderProp(children)

package/es/Tabs/v2/Tab/props.js

@@ -22,5 +22,5 @@
  * SOFTWARE.
  */
 
-const allowedProps = ['variant', 'id', 'index', 'controls', 'isDisabled', 'isSelected', 'onClick', 'onKeyDown', 'children', 'isOverflowScroll'];
+const allowedProps = ['variant', 'id', 'index', 'controls', 'isDisabled', 'isSelected', 'isTabbable', 'onClick', 'onKeyDown', 'onFocus', 'children', 'isOverflowScroll'];
 export { allowedProps };

package/es/Tabs/v2/index.js

@@ -1,4 +1,4 @@
-var _dec, _dec2, _class;
+var _dec, _dec2, _dec3, _class;
 /*
  * The MIT License (MIT)
  *
@@ -28,8 +28,8 @@ import keycode from 'keycode';
 import { View } from '@instructure/ui-view/latest';
 import { matchComponentTypes, safeCloneElement, passthroughProps, withDeterministicId } from '@instructure/ui-react-utils';
 import { logError as error } from '@instructure/console';
-import { Focusable } from '@instructure/ui-focusable';
-import { getBoundingClientRect } from '@instructure/ui-dom-utils';
+import { textDirectionContextConsumer } from '@instructure/ui-i18n';
+import { contains, getBoundingClientRect } from '@instructure/ui-dom-utils';
 import { debounce } from '@instructure/debounce';
 import { px } from '@instructure/ui-utils';
 import { withStyleNew } from '@instructure/emotion';
@@ -43,19 +43,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
 category: components
 ---
 **/
-let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _dec(_class = _dec2(_class = class Tabs extends Component {
+let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _dec3 = textDirectionContextConsumer(), _dec(_class = _dec2(_class = _dec3(_class = class Tabs extends Component {
   static displayName = 'Tabs';
   static componentId = 'Tabs';
   static allowedProps = allowedProps;
   static defaultProps = {
     variant: 'default',
     shouldFocusOnRender: false,
-    tabOverflow: 'stack'
+    tabOverflow: 'stack',
+    activationMode: 'auto'
   };
   static Panel = Panel;
   static Tab = Tab;
   _tabList = null;
-  _focusable = null;
   _tabListPosition;
   _debounced;
   _resizeListener;
@@ -185,26 +185,74 @@ let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _
       }
     }
   }
+  get isRtl() {
+    return this.props.dir === textDirectionContextConsumer.DIRECTION.rtl;
+  }
   handleTabClick = (event, {
     index
   }) => {
-    const nextTab = this.getNextTab(index, 0);
-    this.fireOnChange(event, nextTab);
+    const target = this.getNextTab(this.getTabs(), index, 0);
+    if (target) {
+      this.fireOnChange(event, target);
+    }
   };
   handleTabKeyDown = (event, {
     index
   }) => {
-    let nextTab;
-    if (event.keyCode === keycode.codes.up || event.keyCode === keycode.codes.left) {
-      // Select next tab to the left
-      nextTab = this.getNextTab(index, -1);
-    } else if (event.keyCode === keycode.codes.down || event.keyCode === keycode.codes.right) {
-      // Select next tab to the right
-      nextTab = this.getNextTab(index, 1);
+    const tabs = this.getTabs();
+    let target;
+    let isActivation = false;
+    switch (event.keyCode) {
+      case keycode.codes.left:
+        target = this.getNextTab(tabs, index, this.isRtl ? 1 : -1);
+        break;
+      case keycode.codes.right:
+        target = this.getNextTab(tabs, index, this.isRtl ? -1 : 1);
+        break;
+      case keycode.codes.up:
+        target = this.getNextTab(tabs, index, -1);
+        break;
+      case keycode.codes.down:
+        target = this.getNextTab(tabs, index, 1);
+        break;
+      case keycode.codes.home:
+        target = this.getEdgeTab(tabs, 'first');
+        break;
+      case keycode.codes.end:
+        target = this.getEdgeTab(tabs, 'last');
+        break;
+      case keycode.codes.enter:
+      case keycode.codes.space:
+        target = this.getNextTab(tabs, index, 0);
+        isActivation = true;
+        break;
+      default:
+        return;
     }
-    if (nextTab) {
-      event.preventDefault();
-      this.fireOnChange(event, nextTab);
+    event.stopPropagation();
+    event.preventDefault();
+    if (!target) {
+      return;
+    }
+    if (isActivation || this.props.activationMode !== 'manual') {
+      this.fireOnChange(event, target);
+    }
+    this.focusTab(target.tabDomId);
+  };
+  handleTabFocus = (_event, {
+    id
+  }) => {
+    if (this.state.focusedTabId !== id) {
+      this.setState({
+        focusedTabId: id
+      });
+    }
+  };
+  handleTabListBlur = event => {
+    if (!contains(event.currentTarget, event.relatedTarget)) {
+      this.setState({
+        focusedTabId: undefined
+      });
     }
   };
   handleResize = () => {
@@ -213,67 +261,129 @@ let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _
     });
     this._tabListPosition = getBoundingClientRect(this._tabList);
   };
-  getNextTab(startIndex, step) {
-    const tabs = Children.toArray(this.props.children).map(child => matchComponentTypes(child, [Panel]) && child);
+
+  /**
+   * The single source of truth for tab order, ids and state.
+   */
+  getTabs() {
+    const panels = [];
+    Children.toArray(this.props.children).forEach((child, index) => {
+      if (matchComponentTypes(child, [Panel])) {
+        panels.push({
+          index,
+          panel: child
+        });
+      }
+    });
+    const explicitlySelected = panels.find(({
+      panel
+    }) => panel.props.isSelected && !panel.props.isDisabled);
+    const fallbackIndex = explicitlySelected ? explicitlySelected.index : 0;
+    return panels.map(({
+      index,
+      panel
+    }) => {
+      const baseId = panel.props.id || this.props.deterministicId(`Tabs_${index}`);
+      const isDisabled = !!panel.props.isDisabled;
+      return {
+        index,
+        tabDomId: `tab-${baseId}`,
+        panelDomId: panel.props.id || `panel-${baseId}`,
+        isDisabled,
+        isSelected: !isDisabled && (!!panel.props.isSelected || index === fallbackIndex),
+        panel
+      };
+    });
+  }
+  getNextTab(tabs, startIndex, step) {
     const count = tabs.length;
-    const change = step < 0 ? step + count : step;
-    error(startIndex >= 0 && startIndex < count, `[Tabs] Invalid tab index: '${startIndex}'.`);
-    let nextIndex = startIndex;
-    let nextTab;
-    do {
-      nextIndex = (nextIndex + change) % count;
-      nextTab = tabs[nextIndex];
-    } while (nextTab && nextTab.props && nextTab.props.isDisabled);
-    error(nextIndex >= 0 && nextIndex < count, `[Tabs] Invalid tab index: '${nextIndex}'.`);
-    return {
-      index: nextIndex,
-      id: nextTab.props.id
-    };
+    const from = tabs.findIndex(tab => tab.index === startIndex);
+    error(from >= 0, `[Tabs] Invalid tab index: '${startIndex}'.`);
+    if (from < 0) {
+      return undefined;
+    }
+    if (step === 0) {
+      return tabs[from];
+    }
+    for (let offset = 1; offset <= count; offset++) {
+      const candidate = tabs[((from + step * offset) % count + count) % count];
+      if (!candidate.isDisabled) {
+        return candidate;
+      }
+    }
+    return undefined;
+  }
+  getEdgeTab(tabs, edge) {
+    const enabled = tabs.filter(tab => !tab.isDisabled);
+    return edge === 'first' ? enabled[0] : enabled[enabled.length - 1];
+  }
+  getRovingTabId(tabs) {
+    const {
+      focusedTabId
+    } = this.state;
+    const focused = tabs.find(tab => tab.tabDomId === focusedTabId && !tab.isDisabled);
+    return focused?.tabDomId ?? tabs.find(tab => tab.isSelected)?.tabDomId ?? tabs.find(tab => !tab.isDisabled)?.tabDomId;
   }
   fireOnChange(event, {
     index,
-    id
+    panel,
+    tabDomId
   }) {
     if (typeof this.props.onRequestTabChange === 'function') {
       this.props.onRequestTabChange(event, {
         index,
-        id
+        id: panel.props.id
       });
     }
-
-    // this is needed because keypress cancels scrolling. So we have to trigger the scrolling
+    this.scrollTabIntoView(tabDomId);
+  }
+  scrollTabIntoView(tabDomId) {
     // one "tick" later than the keypress
     setTimeout(() => {
       if (this.state.withTabListOverflow) {
-        const tab = id ? this._tabList.querySelector(`#tab-${CSS.escape(id)}`) : null;
-        this.showActiveTabIfOverlayed(tab);
+        this.showActiveTabIfOverlayed(this._tabList.querySelector(`#${CSS.escape(tabDomId)}`));
       }
     }, 0);
   }
-  createTab(index, generatedId, selected, panel) {
-    const id = panel.props.id || generatedId;
+  createTab(tab, isTabbable) {
+    const {
+      index,
+      tabDomId,
+      panelDomId,
+      isSelected,
+      isDisabled,
+      panel
+    } = tab;
     return _jsx(Tab, {
       variant: this.props.variant,
-      id: `tab-${id}`,
-      controls: panel.props.id || `panel-${id}`,
+      id: tabDomId,
+      controls: panelDomId,
       index: index,
-      isSelected: selected,
-      isDisabled: panel.props.isDisabled,
+      isSelected: isSelected,
+      isDisabled: isDisabled,
+      isTabbable: isTabbable,
       onClick: this.handleTabClick,
       onKeyDown: this.handleTabKeyDown,
+      onFocus: this.handleTabFocus,
       isOverflowScroll: this.props.tabOverflow === 'scroll',
       children: panel.props.renderTitle
     }, `tab-${index}`);
   }
-  clonePanel(index, generatedId, selected, panel, activePanel) {
-    const id = panel.props.id || generatedId;
+  clonePanel(tab, activePanel) {
+    const {
+      index,
+      tabDomId,
+      panelDomId,
+      isSelected,
+      panel
+    } = tab;
 
     // fixHeight can be 0, so simply `fixheight` could return falsy value
     const hasFixedHeight = typeof this.props.fixHeight !== 'undefined';
     const commonProps = {
-      id: panel.props.id || `panel-${id}`,
-      labelledBy: `tab-${id}`,
-      isSelected: selected,
+      id: panelDomId,
+      labelledBy: tabDomId,
+      isSelected,
       variant: this.props.variant,
       maxHeight: !hasFixedHeight ? this.props.maxHeight : undefined,
       minHeight: !hasFixedHeight ? this.props.minHeight : '100%'
@@ -299,14 +409,19 @@ let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _
       });
     }
   }
-  handleFocusableRef = el => {
-    this._focusable = el;
-  };
   handleTabListRef = el => {
     this._tabList = el;
   };
   focus() {
-    this._focusable && typeof this._focusable.focus === 'function' && this._focusable.focus();
+    this.focusTab(this.getRovingTabId(this.getTabs()));
+  }
+  focusTab(tabDomId) {
+    if (!tabDomId) {
+      return;
+    }
+    const tab = this._tabList?.querySelector(`#${CSS.escape(tabDomId)}`);
+    tab?.focus();
+    this.scrollTabIntoView(tabDomId);
   }
   handleScroll = event => {
     if (this.props.tabOverflow !== 'scroll' || !this.state.withTabListOverflow) {
@@ -334,27 +449,24 @@ let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _
       onRequestTabChange,
       tabOverflow,
       styles,
+      dir,
       ...props
     } = this.props;
-    const activePanels = Children.toArray(children).filter(child => matchComponentTypes(child, [Panel])).filter(child => child.props.active);
+    const tabDescriptors = this.getTabs();
+    const rovingTabId = this.getRovingTabId(tabDescriptors);
+    const tabsByIndex = new Map(tabDescriptors.map(tab => [tab.index, tab]));
+    const activePanels = tabDescriptors.map(tab => tab.panel).filter(panel => panel.props.active);
     if (activePanels.length > 1) {
       error(false, `[Tabs] Only one Panel can be marked as active.`);
     }
-    const selectedChildIndex = Children.toArray(children).filter(child => matchComponentTypes(child, [Panel])).findIndex(child => child.props.isSelected && !child.props.isDisabled);
-    const selectedIndex = selectedChildIndex >= 0 ? selectedChildIndex : 0;
-    Children.toArray(children).map((child, index) => {
-      if (matchComponentTypes(child, [Panel])) {
-        const selected = !child.props.isDisabled && (child.props.isSelected || selectedIndex === index);
-        const id = this.props.deterministicId(`Tabs_${index}`);
-        tabs.push(this.createTab(index, id, selected, child));
-        if (activePanels.length === 1) {
-          panels.push(this.clonePanel(index, id, selected, child, activePanels[0]));
-        } else {
-          panels.push(this.clonePanel(index, id, selected, child));
-        }
-      } else {
+    Children.toArray(children).forEach((child, index) => {
+      const tab = tabsByIndex.get(index);
+      if (!tab) {
         panels.push(child);
+        return;
       }
+      tabs.push(this.createTab(tab, tab.tabDomId === rovingTabId));
+      panels.push(this.clonePanel(tab, activePanels.length === 1 ? activePanels[0] : undefined));
     });
     const withScrollFade = tabOverflow === 'scroll' && this.state.withTabListOverflow;
 
@@ -373,23 +485,21 @@ let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _
       as: "div",
       css: styles?.container,
       "data-cid": "Tabs",
-      children: [_jsx(Focusable, {
-        ref: this.handleFocusableRef,
-        children: () => _jsx(View, {
+      children: [_jsx(View, {
+        as: "div",
+        position: "relative",
+        borderRadius: "medium",
+        shouldAnimateFocus: false,
+        css: styles?.tabs,
+        children: _jsxs(View, {
           as: "div",
-          position: "relative",
-          borderRadius: "medium",
-          shouldAnimateFocus: false,
-          css: styles?.tabs,
-          children: _jsxs(View, {
-            as: "div",
-            role: "tablist",
-            css: styles?.tabList,
-            "aria-label": screenReaderLabel,
-            elementRef: this.handleTabListRef,
-            onScroll: this.handleScroll,
-            children: [tabs, withScrollFade && startScrollOverlay, withScrollFade && endScrollOverlay]
-          })
+          role: "tablist",
+          css: styles?.tabList,
+          "aria-label": screenReaderLabel,
+          elementRef: this.handleTabListRef,
+          onScroll: this.handleScroll,
+          onBlur: this.handleTabListBlur,
+          children: [tabs, withScrollFade && startScrollOverlay, withScrollFade && endScrollOverlay]
         })
       }), _jsx("div", {
         css: styles?.panelsContainer,
@@ -397,6 +507,6 @@ let Tabs = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _
       })]
     });
   }
-}) || _class) || _class);
+}) || _class) || _class) || _class);
 export default Tabs;
 export { Tabs, Panel };

package/es/Tabs/v2/props.js

@@ -22,5 +22,5 @@
  * SOFTWARE.
  */
 
-const allowedProps = ['children', 'variant', 'screenReaderLabel', 'onRequestTabChange', 'maxWidth', 'maxHeight', 'minHeight', 'fixHeight', 'margin', 'padding', 'textAlign', 'elementRef', 'tabOverflow', 'shouldFocusOnRender'];
+const allowedProps = ['children', 'variant', 'screenReaderLabel', 'onRequestTabChange', 'maxWidth', 'maxHeight', 'minHeight', 'fixHeight', 'margin', 'padding', 'textAlign', 'elementRef', 'tabOverflow', 'shouldFocusOnRender', 'activationMode'];
 export { allowedProps };

package/lib/Tabs/v2/Tab/index.js

@@ -91,12 +91,30 @@ let Tab = exports.Tab = (_dec = (0, _emotion.withStyleNew)(_styles.default), _de
       });
     }
   };
+  handleFocus = event => {
+    const {
+      onFocus,
+      index,
+      id,
+      isDisabled
+    } = this.props;
+    if (isDisabled) {
+      return;
+    }
+    if (typeof onFocus === 'function') {
+      onFocus(event, {
+        index,
+        id
+      });
+    }
+  };
   render() {
     const {
       id,
       variant,
       isSelected,
       isDisabled,
+      isTabbable = isSelected,
       controls,
       children,
       styles,
@@ -109,11 +127,12 @@ let Tab = exports.Tab = (_dec = (0, _emotion.withStyleNew)(_styles.default), _de
       id: id,
       onClick: this.handleClick,
       onKeyDown: this.handleKeyDown,
+      onFocus: this.handleFocus,
       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 : isTabbable ? 0 : -1,
       position: "relative",
       focusPosition: "offset",
       children: (0, _uiReactUtils.callRenderProp)(children)

package/lib/Tabs/v2/Tab/props.js

@@ -28,4 +28,4 @@ exports.allowedProps = void 0;
  * SOFTWARE.
  */
 
-const allowedProps = exports.allowedProps = ['variant', 'id', 'index', 'controls', 'isDisabled', 'isSelected', 'onClick', 'onKeyDown', 'children', 'isOverflowScroll'];
+const allowedProps = exports.allowedProps = ['variant', 'id', 'index', 'controls', 'isDisabled', 'isSelected', 'isTabbable', 'onClick', 'onKeyDown', 'onFocus', 'children', 'isOverflowScroll'];