feat(Tabs): Contained tabs on the grid

e2e/components/Tabs/Tabs-test.e2e.js

@@ -70,6 +70,14 @@ test.describe('Tabs', () => {
         });
       });
 
+      test('contained fullWidth @vrt', async ({ page }) => {
+        await snapshotStory(page, {
+          component: 'Tabs',
+          id: 'components-tabs--contained-full-width',
+          theme,
+        });
+      });
+
       test('contained with secondary labels @vrt', async ({ page }) => {
         await snapshotStory(page, {
           component: 'Tabs',

packages/react/src/components/Tabs/Tabs.js

@@ -6,6 +6,7 @@
  */
 
 import { ChevronLeft, ChevronRight } from '@carbon/icons-react';
+import { breakpoints } from '@carbon/layout';
 import cx from 'classnames';
 import debounce from 'lodash.debounce';
 import PropTypes from 'prop-types';
@@ -23,6 +24,7 @@ import { usePressable } from './usePressable';
 import deprecate from '../../prop-types/deprecate';
 import { Close } from '@carbon/icons-react';
 import { useEvent } from '../../internal/useEvent';
+import { useMatchMedia } from '../../internal/useMatchMedia';
 
 // Used to manage the overall state of the Tabs
 const TabsContext = React.createContext();
@@ -32,6 +34,9 @@ const TabContext = React.createContext();
 
 // Used to keep track of position in a list of tab panels
 const TabPanelContext = React.createContext();
+
+const lgMediaQuery = `(min-width: ${breakpoints.lg.width})`;
+
 function Tabs({
   children,
   defaultSelectedIndex = 0,
@@ -138,6 +143,7 @@ function TabList({
   children,
   className: customClassName,
   contained = false,
+  fullWidth = false,
   iconSize,
   leftOverflowButtonProps,
   light,
@@ -160,6 +166,14 @@ function TabList({
   const [isScrollable, setIsScrollable] = useState(false);
   const [scrollLeft, setScrollLeft] = useState(null);
 
+  const isLg = useMatchMedia(lgMediaQuery);
+
+  const distributeWidth =
+    fullWidth &&
+    contained &&
+    isLg &&
+    React.Children.toArray(children).length < 9;
+
   // Previous Button
   // VISIBLE IF:
   //   SCROLLABLE
@@ -186,6 +200,7 @@ function TabList({
     [`${prefix}--tabs__icon--default`]: iconSize === 'default',
     [`${prefix}--tabs__icon--lg`]: iconSize === 'lg',
     [`${prefix}--tabs--tall`]: hasSecondaryLabelTabs,
+    [`${prefix}--tabs--full-width`]: distributeWidth,
   });
 
   const isPreviousButtonVisible = ref.current
@@ -451,6 +466,11 @@ TabList.propTypes = {
    */
   contained: PropTypes.bool,
 
+  /**
+   * Used for tabs within a grid, this makes it so tabs span the full container width and have the same width. Only available on contained tabs with <9 children
+   */
+  fullWidth: PropTypes.bool,
+
   /**
    * If using `IconTab`, specify the size of the icon being used.
    */
@@ -651,7 +671,9 @@ const Tab = React.forwardRef(function Tab(
             {<Icon size={16} />}
           </div>
         )}
-        <span className={`${prefix}--tabs__nav-item-label`}>{children}</span>
+        <span className={`${prefix}--tabs__nav-item-label`} title={children}>
+          {children}
+        </span>
         {/* always rendering dismissIcon so we don't lose reference to it, otherwise events do not work when switching from/to dismissable state */}
         <div
           className={cx(`${prefix}--tabs__nav-item--icon`, {
@@ -662,7 +684,9 @@ const Tab = React.forwardRef(function Tab(
         </div>
       </div>
       {hasSecondaryLabel && (
-        <div className={`${prefix}--tabs__nav-item-secondary-label`}>
+        <div
+          className={`${prefix}--tabs__nav-item-secondary-label`}
+          title={secondaryLabel}>
           {secondaryLabel}
         </div>
       )}

packages/react/src/components/Tabs/Tabs.mdx

@@ -1,5 +1,6 @@
-import { Props, Preview, Story } from '@storybook/addon-docs';
+import { Props, Preview, Story, Canvas } from '@storybook/addon-docs';
 import { Tabs, TabList, Tab, TabPanels, TabPanel } from './Tabs';
+import { Grid, Column } from '../Grid'
 
 # Tabs
 
@@ -9,6 +10,8 @@ import { Tabs, TabList, Tab, TabPanels, TabPanel } from './Tabs';
  | 
 [Accessibility](https://www.carbondesignsystem.com/components/tabs/accessibility)
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## Table of Contents
 
 - [Overview](#overview)
@@ -18,12 +21,15 @@ import { Tabs, TabList, Tab, TabPanels, TabPanel } from './Tabs';
   - [Dismissable Tabs](#dismissable-tabs)
 - [Component API](#component-api)
   - [Tab - render content on click](#tab---render-content-on-click)
+  - [Tabs and the Grid - fullWidth prop](#tabs-and-the-grid---fullwidth-prop)
 - [V11](#v11)
   - [Tabs composition](#tabs-composition)
   - [Various updates](#various-updates)
   - [Max width](#max-width)
 - [Feedback](#feedback)
 
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Overview
 
 Use tabs to allow users to navigate easily between views within the same
@@ -201,6 +207,51 @@ loaded when the Tab is clicked. In v11, to do this, you can this by setting
 </Tabs>
 ```
 
+### Tabs and the Grid - fullWidth prop
+
+By default, a `Tab` component is only as wide as it's content. This posses difficulties when trying to align tabs to the grid.
+Alternatively, you may choose to use the `fullWidth` prop to allow Tab elements to grow as big wide their container allows.
+Note that this feature is *only available* for `contained` tabs with less than 9 tabs, otherwise the prop will be ignored.
+`fullWidth` paired up with a wrapping `Grid` component will allow for "grid-aware" tabs:
+
+<Canvas>
+  <Grid condensed>
+    <Column lg={16} md={8} sm={4}>
+      <Tabs>
+        <TabList aria-label="List of tabs" contained fullWidth>
+          <Tab>Tab Label 1</Tab>
+          <Tab>Tab Label 2</Tab>
+          <Tab disabled>Tab Label 3</Tab>
+        </TabList>
+        <TabPanels>
+          <TabPanel>Tab Panel 1</TabPanel>
+          <TabPanel>Tab Panel 2</TabPanel>
+          <TabPanel>Tab Panel 3</TabPanel>
+        </TabPanels>
+      </Tabs>
+    </Column>
+  </Grid>
+</Canvas>
+
+```jsx
+    <Grid condensed>
+      <Column lg={16} md={8} sm={4}>
+        <Tabs>
+          <TabList aria-label="List of tabs" contained fullWidth>
+            <Tab>Tab Label 1</Tab>
+            <Tab>Tab Label 2</Tab>
+            <Tab disabled>Tab Label 3</Tab>
+          </TabList>
+          <TabPanels>
+            <TabPanel>Tab Panel 1</TabPanel>
+            <TabPanel>Tab Panel 2</TabPanel>
+            <TabPanel>Tab Panel 3</TabPanel>
+          </TabPanels>
+        </Tabs>
+      </Column>
+    </Grid>
+```
+
 ## V11
 
 ### Tabs composition