From c3b9f31fa2d7ca04edcdc66059f9e7afac95f4c2 Mon Sep 17 00:00:00 2001 From: Lena Morita Date: Sat, 21 Dec 2024 02:31:54 +0900 Subject: [PATCH] Tabs: Auto-generate README --- packages/components/src/tabs/README.md | 336 ++++++++---------- .../components/src/tabs/docs-manifest.json | 22 ++ packages/components/src/tabs/index.tsx | 25 +- .../src/tabs/stories/best-practices.mdx | 92 +++++ packages/components/src/tabs/tab.tsx | 6 + packages/components/src/tabs/tablist.tsx | 5 + packages/components/src/tabs/tabpanel.tsx | 3 + packages/components/src/tabs/types.ts | 6 +- 8 files changed, 301 insertions(+), 194 deletions(-) create mode 100644 packages/components/src/tabs/docs-manifest.json create mode 100644 packages/components/src/tabs/stories/best-practices.mdx diff --git a/packages/components/src/tabs/README.md b/packages/components/src/tabs/README.md index 9c7e846046c904..7fdfc8dc42c56c 100644 --- a/packages/components/src/tabs/README.md +++ b/packages/components/src/tabs/README.md @@ -1,254 +1,216 @@ # Tabs -
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. -
- -Tabs is a collection of React components that combine to render an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). - -Tabs organizes content across different screens, data sets, and interactions. It has two sections: a list of tabs, and the view to show when tabs are chosen. - -## Development guidelines - -### Usage - -#### Uncontrolled Mode - -Tabs can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `defaultTabId` prop can be used to set the initially selected tab. If this prop is not set, the first tab will be selected by default. In addition, in most cases where the currently active tab becomes disabled or otherwise unavailable, uncontrolled mode will automatically fall back to selecting the first available tab. - -```jsx -import { Tabs } from '@wordpress/components'; - -const onSelect = ( tabName ) => { - console.log( 'Selecting tab', tabName ); -}; - -const MyUncontrolledTabs = () => ( - - - - Tab 1 - - - Tab 2 - - - Tab 3 - - - -

Selected tab: Tab 1

- - -

Selected tab: Tab 2

- - -

Selected tab: Tab 3

- - - ); -``` - -#### Controlled Mode - -Tabs can also be used in a controlled mode, where the parent component specifies the `selectedTabId` and the `onSelect` props to control tab selection. In this mode, the `defaultTabId` prop will be ignored if it is provided. If the `selectedTabId` is `null`, no tab is selected. In this mode, if the currently selected tab becomes disabled or otherwise unavailable, the component will _not_ fall back to another available tab, leaving the controlling component in charge of implementing the desired logic. - -```jsx -import { Tabs } from '@wordpress/components'; - const [ selectedTabId, setSelectedTabId ] = useState< - string | undefined | null - >(); - -const onSelect = ( tabName ) => { - console.log( 'Selecting tab', tabName ); -}; - -const MyControlledTabs = () => ( - { - setSelectedTabId( selectedId ); - onSelect( selectedId ); - } } - > - - - Tab 1 - - - Tab 2 - - - Tab 3 - - - -

Selected tab: Tab 1

- - -

Selected tab: Tab 2

- - -

Selected tab: Tab 3

- - - ); -``` - -### Components and Sub-components - -Tabs is comprised of four individual components: -- `Tabs`: a wrapper component and context provider. It is responsible for managing the state of the tabs and rendering the `TabList` and `TabPanels`. -- `TabList`: a wrapper component for the `Tab` components. It is responsible for rendering the list of tabs. -- `Tab`: renders a single tab. The currently active tab receives default styling that can be overridden with CSS targeting [aria-selected="true"]. -- `TabPanel`: renders the content to display for a single tab once that tab is selected. - -#### Tabs - -##### Props - -###### `children`: `React.ReactNode` - -The children elements, which should include one instance of the `Tabs.Tablist` component and as many instances of the `Tabs.TabPanel` components as there are `Tabs.Tab` components. - -- Required: Yes - -###### `selectOnMove`: `boolean` - -Determines if the tab should be selected when it receives focus. If set to `false`, the tab will only be selected upon clicking, not when using arrow keys to shift focus (manual tab activation). See the [official W3C docs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) for more info. - -- Required: No -- Default: `true` - -###### `selectedTabId`: `string | null` + -The id of the tab whose panel is currently visible. +

See the WordPress Storybook for more detailed, interactive documentation.

-If left `undefined`, it will be automatically set to the first enabled tab, and the component assumes it is being used in "uncontrolled" mode. +Tabs is a collection of React components that combine to render +an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). -Consequently, any value different than `undefined` will set the component in "controlled" mode. When in "controlled" mode, the `null` value will result in no tabs being selected, and the tablist becoming tabbable. +Tabs organizes content across different screens, data sets, and interactions. +It has two sections: a list of tabs, and the view to show when tabs are chosen. -- Required: No +`Tabs` itself is a wrapper component and context provider. +It is responsible for managing the state of the tabs, and rendering the `TabList` and `TabPanels`. -###### `defaultTabId`: `string | null` +## Props -The id of the tab whose panel is currently visible. +### `activeTabId` -If left `undefined`, it will be automatically set to the first enabled tab. If set to `null`, no tab will be selected, and the tablist will be tabbable. +The current active tab `id`. The active tab is the tab element within the +tablist widget that has DOM focus. -_Note: this prop will be overridden by the `selectedTabId` prop if it is provided (meaning the component will be used in "controlled" mode)._ +- `null` represents the tablist (ie. the base composite element). Users + will be able to navigate out of it using arrow keys. +- If `activeTabId` is initially set to `null`, the base composite element + itself will have focus and users will be able to navigate to it using + arrow keys.activeTabId -- Required: No + - Type: `string` + - Required: No -###### `onSelect`: `( ( selectedId: string | null | undefined ) => void )` +### `children` -The function called when the `selectedTabId` changes. +The children elements, which should include one instance of the +`Tabs.Tablist` component and as many instances of the `Tabs.TabPanel` +components as there are `Tabs.Tab` components. -- Required: No -- Default: `noop` + - Type: `ReactNode` + - Required: Yes -###### `activeTabId`: `string | null` +### `defaultTabId` -The current active tab `id`. The active tab is the tab element within the tablist widget that has DOM focus. +The id of the tab whose panel is currently visible. -- `null` represents the tablist (ie. the base composite element). Users - will be able to navigate out of it using arrow keys; -- If `activeTabId` is initially set to `null`, the base composite element - itself will have focus and users will be able to navigate to it using - arrow keys. +If left `undefined`, it will be automatically set to the first enabled +tab. If set to `null`, no tab will be selected, and the tablist will be +tabbable. -- Required: No +Note: this prop will be overridden by the `selectedTabId` prop if it is +provided (meaning the component will be used in "controlled" mode). -###### `defaultActiveTabId`: `string | null` + - Type: `string` + - Required: No -The tab id that should be active by default when the composite widget is rendered. If `null`, the tablist element itself will have focus and users will be able to navigate to it using arrow keys. If `undefined`, the first enabled item will be focused. +### `defaultActiveTabId` -_Note: this prop will be overridden by the `activeTabId` prop if it is provided._ +The tab id that should be active by default when the composite widget is +rendered. If `null`, the tablist element itself will have focus +and users will be able to navigate to it using arrow keys. If `undefined`, +the first enabled item will be focused. -- Required: No +Note: this prop will be overridden by the `activeTabId` prop if it is +provided. -###### `onActiveTabIdChange`: `( ( activeId: string | null | undefined ) => void )` + - Type: `string` + - Required: No + +### `onSelect` The function called when the `selectedTabId` changes. -- Required: No -- Default: `noop` + - Type: `(selectedId: string) => void` + - Required: No + +### `onActiveTabIdChange` -###### `orientation`: `'horizontal' | 'vertical' | 'both'` +A callback that gets called when the `activeTabId` state changes. -Defines the orientation of the tablist and determines which arrow keys can be used to move focus: + - Type: `(activeId: string) => void` + - Required: No -- `both`: all arrow keys work; -- `horizontal`: only left and right arrow keys work; +### `orientation` + +Defines the orientation of the tablist and determines which arrow keys +can be used to move focus: + +- `both`: all arrow keys work. +- `horizontal`: only left and right arrow keys work. - `vertical`: only up and down arrow keys work. -- Required: No -- Default: `horizontal` + - Type: `"horizontal" | "vertical" | "both"` + - Required: No + - Default: `"horizontal"` + +### `selectOnMove` -#### TabList +Determines if the tab should be selected when it receives focus. If set to +`false`, the tab will only be selected upon clicking, not when using arrow +keys to shift focus (manual tab activation). See the [official W3C docs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) +for more info. -##### Props + - Type: `boolean` + - Required: No + - Default: `true` -###### `children`: `React.ReactNode` +### `selectedTabId` -The children elements, which should include one or more instances of the `Tabs.Tab` component. +The id of the tab whose panel is currently visible. + +If left `undefined`, it will be automatically set to the first enabled +tab, and the component assumes it is being used in "uncontrolled" mode. + +Consequently, any value different than `undefined` will set the component +in "controlled" mode. When in "controlled" mode, the `null` value will +result in no tabs being selected, and the tablist becoming tabbable. + + - Type: `string` + - Required: No + +## Subcomponents + +### Tabs.TabList + +A wrapper component for the `Tab` components. + +It is responsible for rendering the list of tabs. -- Required: No +#### Props -#### Tab +##### `children` -##### Props +The children elements, which should include one or more instances of the +`Tabs.Tab` component. -###### `tabId`: `string` + - Type: `ReactNode` + - Required: Yes -The unique ID of the tab. It will be used to register the tab and match it to a corresponding `Tabs.TabPanel` component. If not provided, a unique ID will be automatically generated. +### Tabs.Tab -- Required: Yes +Renders a single tab. -###### `children`: `React.ReactNode` +The currently active tab receives default styling that can be +overridden with CSS targeting `[aria-selected="true"]`. + +#### Props + +##### `children` The contents of the tab. -- Required: No + - Type: `ReactNode` + - Required: No -###### `disabled`: `boolean` +##### `disabled` -Determines if the tab should be disabled. Note that disabled tabs can still be accessed via the keyboard when navigating through the tablist. +Determines if the tab should be disabled. Note that disabled tabs can +still be accessed via the keyboard when navigating through the tablist. -- Required: No -- Default: `false` + - Type: `boolean` + - Required: No + - Default: `false` -###### `render`: `React.ReactNode` +##### `render` -Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged. +Allows the component to be rendered as a different HTML element or React +component. The value can be a React element or a function that takes in the +original component props and gives back a React element with the props +merged. By default, the tab will be rendered as a `button` element. -- Required: No + - Type: `RenderProp & { ref?: Ref; }> | ReactElement>` + - Required: No -#### TabPanel +##### `tabId` -##### Props +The unique ID of the tab. It will be used to register the tab and match +it to a corresponding `Tabs.TabPanel` component. -###### `children`: `React.ReactNode` + - Type: `string` + - Required: Yes -The contents of the tab panel. +### Tabs.TabPanel -- Required: No +Renders the content to display for a single tab once that tab is selected. -###### `tabId`: `string` +#### Props -The unique `id` of the `Tabs.Tab` component controlling this panel. This connection is used to assign the `aria-labelledby` attribute to the tab panel and to determine if the tab panel should be visible. +##### `children` -If not provided, this link is automatically established by matching the order of `Tabs.Tab` and `Tabs.TabPanel` elements in the DOM. +The contents of the tab panel. -- Required: Yes + - Type: `ReactNode` + - Required: No -###### `focusable`: `boolean` +##### `focusable` Determines whether or not the tabpanel element should be focusable. +If `false`, pressing the tab key will skip over the tabpanel, and instead +focus on the first focusable element in the panel (if there is one). + + - Type: `boolean` + - Required: No + - Default: `true` + +##### `tabId` + +The unique `id` of the `Tabs.Tab` component controlling this panel. This +connection is used to assign the `aria-labelledby` attribute to the tab +panel and to determine if the tab panel should be visible. -If `false`, pressing the tab key will skip over the tabpanel, and instead focus on the first focusable element in the panel (if there is one). +If not provided, this link is automatically established by matching the +order of `Tabs.Tab` and `Tabs.TabPanel` elements in the DOM. -- Required: No -- Default: `true` + - Type: `string` + - Required: Yes diff --git a/packages/components/src/tabs/docs-manifest.json b/packages/components/src/tabs/docs-manifest.json new file mode 100644 index 00000000000000..fc24b177ef6163 --- /dev/null +++ b/packages/components/src/tabs/docs-manifest.json @@ -0,0 +1,22 @@ +{ + "$schema": "../../schemas/docs-manifest.json", + "displayName": "Tabs", + "filePath": "./index.tsx", + "subcomponents": [ + { + "displayName": "TabList", + "preferredDisplayName": "Tabs.TabList", + "filePath": "./tablist.tsx" + }, + { + "displayName": "Tab", + "preferredDisplayName": "Tabs.Tab", + "filePath": "./tab.tsx" + }, + { + "displayName": "TabPanel", + "preferredDisplayName": "Tabs.TabPanel", + "filePath": "./tabpanel.tsx" + } + ] +} diff --git a/packages/components/src/tabs/index.tsx b/packages/components/src/tabs/index.tsx index 819d259395daf8..295614c5230a0d 100644 --- a/packages/components/src/tabs/index.tsx +++ b/packages/components/src/tabs/index.tsx @@ -36,11 +36,14 @@ function internalToExternalTabId( } /** - * Display one panel of content at a time with a tabbed interface, based on the - * WAI-ARIA Tabs Pattern⁠. + * Tabs is a collection of React components that combine to render + * an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). * - * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ - * ``` + * Tabs organizes content across different screens, data sets, and interactions. + * It has two sections: a list of tabs, and the view to show when tabs are chosen. + * + * `Tabs` itself is a wrapper component and context provider. + * It is responsible for managing the state of the tabs, and rendering the `TabList` and `TabPanels`. */ export const Tabs = Object.assign( function Tabs( { @@ -121,12 +124,26 @@ export const Tabs = Object.assign( ); }, { + /** + * Renders a single tab. + * + * The currently active tab receives default styling that can be + * overridden with CSS targeting `[aria-selected="true"]`. + */ Tab: Object.assign( Tab, { displayName: 'Tabs.Tab', } ), + /** + * A wrapper component for the `Tab` components. + * + * It is responsible for rendering the list of tabs. + */ TabList: Object.assign( TabList, { displayName: 'Tabs.TabList', } ), + /** + * Renders the content to display for a single tab once that tab is selected. + */ TabPanel: Object.assign( TabPanel, { displayName: 'Tabs.TabPanel', } ), diff --git a/packages/components/src/tabs/stories/best-practices.mdx b/packages/components/src/tabs/stories/best-practices.mdx new file mode 100644 index 00000000000000..c0529766238e5f --- /dev/null +++ b/packages/components/src/tabs/stories/best-practices.mdx @@ -0,0 +1,92 @@ +import { Meta } from '@storybook/blocks'; + +import * as TabsStories from './index.story'; + + + +# Tabs + +## Usage + +### Uncontrolled Mode + +Tabs can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `defaultTabId` prop can be used to set the initially selected tab. If this prop is not set, the first tab will be selected by default. In addition, in most cases where the currently active tab becomes disabled or otherwise unavailable, uncontrolled mode will automatically fall back to selecting the first available tab. + +```jsx +import { Tabs } from '@wordpress/components'; + +const onSelect = ( tabName ) => { + console.log( 'Selecting tab', tabName ); +}; + +const MyUncontrolledTabs = () => ( + + + + Tab 1 + + + Tab 2 + + + Tab 3 + + + +

Selected tab: Tab 1

+ + +

Selected tab: Tab 2

+ + +

Selected tab: Tab 3

+ + + ); +``` + +### Controlled Mode + +Tabs can also be used in a controlled mode, where the parent component specifies the `selectedTabId` and the `onSelect` props to control tab selection. In this mode, the `defaultTabId` prop will be ignored if it is provided. If the `selectedTabId` is `null`, no tab is selected. In this mode, if the currently selected tab becomes disabled or otherwise unavailable, the component will _not_ fall back to another available tab, leaving the controlling component in charge of implementing the desired logic. + +```tsx +import { Tabs } from '@wordpress/components'; + const [ selectedTabId, setSelectedTabId ] = useState< + string | undefined | null + >(); + +const onSelect = ( tabName ) => { + console.log( 'Selecting tab', tabName ); +}; + +const MyControlledTabs = () => ( + { + setSelectedTabId( selectedId ); + onSelect( selectedId ); + } } + > + + + Tab 1 + + + Tab 2 + + + Tab 3 + + + +

Selected tab: Tab 1

+ + +

Selected tab: Tab 2

+ + +

Selected tab: Tab 3

+ + + ); +``` \ No newline at end of file diff --git a/packages/components/src/tabs/tab.tsx b/packages/components/src/tabs/tab.tsx index 8226d0589f08c8..2e1ec828c9f63c 100644 --- a/packages/components/src/tabs/tab.tsx +++ b/packages/components/src/tabs/tab.tsx @@ -18,6 +18,12 @@ import { import type { WordPressComponentProps } from '../context'; import { chevronRight } from '@wordpress/icons'; +/** + * Renders a single tab. + * + * The currently active tab receives default styling that can be + * overridden with CSS targeting `[aria-selected="true"]`. + */ export const Tab = forwardRef< HTMLButtonElement, Omit< WordPressComponentProps< TabProps, 'button', false >, 'id' > diff --git a/packages/components/src/tabs/tablist.tsx b/packages/components/src/tabs/tablist.tsx index b7cfef7e19a096..1fe87213762588 100644 --- a/packages/components/src/tabs/tablist.tsx +++ b/packages/components/src/tabs/tablist.tsx @@ -67,6 +67,11 @@ function useScrollRectIntoView( }, [ margin, parent, rect ] ); } +/** + * A wrapper component for the `Tab` components. + * + * It is responsible for rendering the list of tabs. + */ export const TabList = forwardRef< HTMLDivElement, WordPressComponentProps< TabListProps, 'div', false > diff --git a/packages/components/src/tabs/tabpanel.tsx b/packages/components/src/tabs/tabpanel.tsx index 512b2609682722..6b9cbbf5df8d98 100644 --- a/packages/components/src/tabs/tabpanel.tsx +++ b/packages/components/src/tabs/tabpanel.tsx @@ -18,6 +18,9 @@ import warning from '@wordpress/warning'; import { useTabsContext } from './context'; import type { WordPressComponentProps } from '../context'; +/** + * Renders the content to display for a single tab once that tab is selected. + */ export const TabPanel = forwardRef< HTMLDivElement, Omit< WordPressComponentProps< TabPanelProps, 'div', false >, 'id' > diff --git a/packages/components/src/tabs/types.ts b/packages/components/src/tabs/types.ts index 959a82509a05d6..7f8a55e28bf9b8 100644 --- a/packages/components/src/tabs/types.ts +++ b/packages/components/src/tabs/types.ts @@ -26,12 +26,10 @@ export type TabsProps = { /** * Determines if the tab should be selected when it receives focus. If set to * `false`, the tab will only be selected upon clicking, not when using arrow - * keys to shift focus (manual tab activation). See the official W3C docs + * keys to shift focus (manual tab activation). See the [official W3C docs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) * for more info. * * @default true - * - * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/ */ selectOnMove?: Ariakit.TabStoreProps[ 'selectOnMove' ]; /** @@ -63,6 +61,7 @@ export type TabsProps = { /** * The current active tab `id`. The active tab is the tab element within the * tablist widget that has DOM focus. + * * - `null` represents the tablist (ie. the base composite element). Users * will be able to navigate out of it using arrow keys. * - If `activeTabId` is initially set to `null`, the base composite element @@ -87,6 +86,7 @@ export type TabsProps = { /** * Defines the orientation of the tablist and determines which arrow keys * can be used to move focus: + * * - `both`: all arrow keys work. * - `horizontal`: only left and right arrow keys work. * - `vertical`: only up and down arrow keys work.