[Tabs] Add new experimental Tabs API

.eslintrc.js

@@ -137,6 +137,7 @@ module.exports = {
         // tests are not driven by assistive technology
         // add `jsx-a11y` rules once you encounter them in tests
         'jsx-a11y/click-events-have-key-events': 'off',
+        'jsx-a11y/control-has-associated-label': 'off',
         'jsx-a11y/iframe-has-title': 'off',
         'jsx-a11y/mouse-events-have-key-events': 'off',
         'jsx-a11y/no-noninteractive-tabindex': 'off',

docs/pages/api-docs/tab-context.js

@@ -0,0 +1,15 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown';
+
+const pageFilename = 'api/tab-context';
+const requireRaw = require.context('!raw-loader!./', false, /\/tab-context\.md$/);
+
+export default function Page({ docs }) {
+  return <MarkdownDocs docs={docs} />;
+}
+
+Page.getInitialProps = () => {
+  const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw });
+  return { demos, docs };
+};

docs/pages/api-docs/tab-context.md

@@ -0,0 +1,35 @@
+---
+filename: /packages/material-ui-lab/src/TabContext/TabContext.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# TabContext API
+
+<p class="description">The API documentation of the TabContext React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import TabContext from '@material-ui/lab/TabContext';
+// or
+import { TabContext } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name">children</span> | <span class="prop-type">node</span> |  | The content of the component. |
+| <span class="prop-name required">value&nbsp;*</span> | <span class="prop-type">any</span> |  | The value of the currently selected `Tab`. If you don't want any selected `Tab`, you can set this property to `false`. |
+
+The component cannot hold a ref.
+
+Any other props supplied will be provided to the root element (native element).
+

docs/pages/api-docs/tab-list.js

@@ -0,0 +1,15 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown';
+
+const pageFilename = 'api/tab-list';
+const requireRaw = require.context('!raw-loader!./', false, /\/tab-list\.md$/);
+
+export default function Page({ docs }) {
+  return <MarkdownDocs docs={docs} />;
+}
+
+Page.getInitialProps = () => {
+  const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw });
+  return { demos, docs };
+};

docs/pages/api-docs/tab-list.md

@@ -0,0 +1,34 @@
+---
+filename: /packages/material-ui-lab/src/TabList/TabList.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# TabList API
+
+<p class="description">The API documentation of the TabList React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import TabList from '@material-ui/lab/TabList';
+// or
+import { TabList } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name">children</span> | <span class="prop-type">Array&lt;element&gt;</span> |  |  |
+
+The component cannot hold a ref.
+
+Any other props supplied will be provided to the root element (native element).
+

docs/pages/api-docs/tab-panel.js

@@ -0,0 +1,15 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown';
+
+const pageFilename = 'api/tab-panel';
+const requireRaw = require.context('!raw-loader!./', false, /\/tab-panel\.md$/);
+
+export default function Page({ docs }) {
+  return <MarkdownDocs docs={docs} />;
+}
+
+Page.getInitialProps = () => {
+  const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw });
+  return { demos, docs };
+};

docs/pages/api-docs/tab-panel.md

@@ -0,0 +1,53 @@
+---
+filename: /packages/material-ui-lab/src/TabPanel/TabPanel.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# TabPanel API
+
+<p class="description">The API documentation of the TabPanel React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import TabPanel from '@material-ui/lab/TabPanel';
+// or
+import { TabPanel } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+## Component name
+
+The `MuiTabPanel` name can be used for providing [default props](/customization/globals/#default-props) or [style overrides](/customization/globals/#css) at the theme level.
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name required">activeValue&nbsp;*</span> | <span class="prop-type">any</span> |  |  |
+| <span class="prop-name">children</span> | <span class="prop-type">node</span> |  |  |
+| <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
+| <span class="prop-name required">value&nbsp;*</span> | <span class="prop-type">any</span> |  |  |
+
+The `ref` is forwarded to the root element.
+
+Any other props supplied will be provided to the root element (native element).
+
+## CSS
+
+| Rule name | Global class | Description |
+|:-----|:-------------|:------------|
+| <span class="prop-name">root</span> | <span class="prop-name">.MuiTabPanel-root</span> | Styles applied to the root element.
+
+You can override the style of the component thanks to one of these customization points:
+
+- With a rule name of the [`classes` object prop](/customization/components/#overriding-styles-with-classes).
+- With a [global class name](/customization/components/#overriding-styles-with-global-class-names).
+- With a theme and an [`overrides` property](/customization/globals/#css).
+
+If that's not sufficient, you can check the [implementation of the component](https://github.com/mui-org/material-ui/blob/master/packages/material-ui-lab/src/TabPanel/TabPanel.js) for more detail.
+

docs/pages/api-docs/tab-panels.js

@@ -0,0 +1,15 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown';
+
+const pageFilename = 'api/tab-panels';
+const requireRaw = require.context('!raw-loader!./', false, /\/tab-panels\.md$/);
+
+export default function Page({ docs }) {
+  return <MarkdownDocs docs={docs} />;
+}
+
+Page.getInitialProps = () => {
+  const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw });
+  return { demos, docs };
+};

docs/pages/api-docs/tab-panels.md

@@ -0,0 +1,34 @@
+---
+filename: /packages/material-ui-lab/src/TabPanels/TabPanels.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# TabPanels API
+
+<p class="description">The API documentation of the TabPanels React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import TabPanels from '@material-ui/lab/TabPanels';
+// or
+import { TabPanels } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name required">children&nbsp;*</span> | <span class="prop-type">Array&lt;element&gt;</span> |  | The content of the component. |
+
+The component cannot hold a ref.
+
+Any other props supplied will be provided to the root element (native element).
+

docs/src/pages/components/tabs/LabTabs.js

@@ -0,0 +1,43 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import AppBar from '@material-ui/core/AppBar';
+import Tab from '@material-ui/core/Tab';
+import TabContext from '@material-ui/lab/TabContext';
+import TabList from '@material-ui/lab/TabList';
+import TabPanel from '@material-ui/lab/TabPanel';
+import TabPanels from '@material-ui/lab/TabPanels';
+
+const useStyles = makeStyles((theme) => ({
+  root: {
+    flexGrow: 1,
+    backgroundColor: theme.palette.background.paper,
+  },
+}));
+
+export default function LabTabs() {
+  const classes = useStyles();
+  const [value, setValue] = React.useState(0);
+
+  const handleChange = (event, newValue) => {
+    setValue(newValue);
+  };
+
+  return (
+    <div className={classes.root}>
+      <TabContext value={value}>
+        <AppBar position="static">
+          <TabList onChange={handleChange} aria-label="simple tabs example">
+            <Tab label="Item One" />
+            <Tab label="Item Two" />
+            <Tab label="Item Three" />
+          </TabList>
+        </AppBar>
+        <TabPanels>
+          <TabPanel>Item One</TabPanel>
+          <TabPanel>Item Two</TabPanel>
+          <TabPanel>Item Three</TabPanel>
+        </TabPanels>
+      </TabContext>
+    </div>
+  );
+}

docs/src/pages/components/tabs/LabTabs.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { makeStyles, Theme } from '@material-ui/core/styles';
+import AppBar from '@material-ui/core/AppBar';
+import Tab from '@material-ui/core/Tab';
+import TabContext from '@material-ui/lab/TabContext';
+import TabList from '@material-ui/lab/TabList';
+import TabPanel from '@material-ui/lab/TabPanel';
+import TabPanels from '@material-ui/lab/TabPanels';
+
+const useStyles = makeStyles((theme: Theme) => ({
+  root: {
+    flexGrow: 1,
+    backgroundColor: theme.palette.background.paper,
+  },
+}));
+
+export default function LabTabs() {
+  const classes = useStyles();
+  const [value, setValue] = React.useState(0);
+
+  const handleChange = (event: React.ChangeEvent<{}>, newValue: number) => {
+    setValue(newValue);
+  };
+
+  return (
+    <div className={classes.root}>
+      <TabContext value={value}>
+        <AppBar position="static">
+          <TabList onChange={handleChange} aria-label="simple tabs example">
+            <Tab label="Item One" />
+            <Tab label="Item Two" />
+            <Tab label="Item Three" />
+          </TabList>
+        </AppBar>
+        <TabPanels>
+          <TabPanel>Item One</TabPanel>
+          <TabPanel>Item Two</TabPanel>
+          <TabPanel>Item Three</TabPanel>
+        </TabPanels>
+      </TabContext>
+    </div>
+  );
+}

docs/src/pages/components/tabs/tabs.md

@@ -60,7 +60,7 @@ Left and right scroll buttons will be presented regardless of the viewport width
 
 ### Prevent Scroll Buttons
 
-Left and right scroll buttons will never be presented.  All scrolling must be initiated through user agent scrolling mechanisms (e.g. left/right swipe, shift-mousewheel, etc.)
+Left and right scroll buttons will never be presented. All scrolling must be initiated through user agent scrolling mechanisms (e.g. left/right swipe, shift-mousewheel, etc.)
 
 {{"demo": "pages/components/tabs/ScrollableTabsButtonPrevent.js", "bg": true}}
 
@@ -90,3 +90,10 @@ Tab labels may be either all icons or all text.
 {{"demo": "pages/components/tabs/IconTabs.js", "bg": true}}
 
 {{"demo": "pages/components/tabs/IconLabelTabs.js", "bg": true}}
+
+## Experimental Tabs API
+
+`@material-ui/lab` offers utility components that inject props to implement accessible tabs
+following [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices/#tabpanel).
+
+{{"demo": "pages/components/tabs/LabTabs.js", "bg": true}}

packages/material-ui-lab/src/TabContext/TabContext.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+export interface TabContextValue {
+  panelPrefix: string;
+  tabPrefix: string;
+  value: unknown;
+}
+
+export interface TabContextProps {
+  children?: React.ReactNode;
+  /**
+   * The value of the currently selected `Tab`.
+   * If you don't want any selected `Tab`, you can set this property to `false`.
+   */
+  value: unknown;
+}
+/**
+ *
+ * API:
+ *
+ * - [TabContext API](https://material-ui.com/api/tab-context/)
+ */
+export default function TabContext(props: TabContextProps): JSX.Element;
+export function useTabContext(): TabContextValue | null;