refactor(v2): render all tab panels at once (#3706)

* refactor(v2): render all tab panels at once

* Add ability to choose way to load tabs

packages/docusaurus-theme-classic/src/theme/TabItem/index.tsx

@@ -8,8 +8,12 @@
 import React from 'react';
 import type {Props} from '@theme/TabItem';
 
-function TabItem(props: Props): JSX.Element {
-  return <div>{props.children}</div>;
+function TabItem({children, hidden, className}: Props): JSX.Element {
+  return (
+    <div role="tabpanel" {...{hidden, className}}>
+      {children}
+    </div>
+  );
 }
 
 export default TabItem;

packages/docusaurus-theme-classic/src/theme/Tabs/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState, Children, ReactElement} from 'react';
+import React, {useState, cloneElement} from 'react';
 import useUserPreferencesContext from '@theme/hooks/useUserPreferencesContext';
 import type {Props} from '@theme/Tabs';
 
@@ -19,7 +19,15 @@ const keys = {
 };
 
 function Tabs(props: Props): JSX.Element {
-  const {block, children, defaultValue, values, groupId, className} = props;
+  const {
+    lazy,
+    block,
+    children,
+    defaultValue,
+    values,
+    groupId,
+    className,
+  } = props;
   const {tabGroupChoices, setTabGroupChoices} = useUserPreferencesContext();
   const [selectedValue, setSelectedValue] = useState(defaultValue);
 
@@ -109,15 +117,24 @@ function Tabs(props: Props): JSX.Element {
           </li>
         ))}
       </ul>
-      <div role="tabpanel" className="margin-vert--md">
-        {
-          Children.toArray(children).filter(
-            (child) =>
-              (child as ReactElement<{value: string}>).props.value ===
-              selectedValue,
-          )[0]
-        }
+
+      {lazy ? (
+        cloneElement(
+          children.filter(
+            (tabItem) => tabItem.props.value === selectedValue,
+          )[0],
+          {className: 'margin-vert--md'},
+        )
+      ) : (
+        <div className="margin-vert--md">
+          {children.map((tabItem, i) =>
+            cloneElement(tabItem, {
+              key: i,
+              hidden: tabItem.props.value !== selectedValue,
+            }),
+          )}
         </div>
+      )}
     </div>
   );
 }

packages/docusaurus-theme-classic/src/types.d.ts

@@ -374,7 +374,12 @@ declare module '@theme/NavbarItem' {
 declare module '@theme/TabItem' {
   import type {ReactNode} from 'react';
 
-  export type Props = {readonly children: ReactNode};
+  export type Props = {
+    readonly children: ReactNode;
+    readonly value: string;
+    readonly hidden: boolean;
+    readonly className: string;
+  };
 
   const TabItem: () => JSX.Element;
   export default TabItem;
@@ -382,10 +387,12 @@ declare module '@theme/TabItem' {
 
 declare module '@theme/Tabs' {
   import type {ReactElement} from 'react';
+  import type {Props as TabItemProps} from '@theme/TabItem';
 
   export type Props = {
+    readonly lazy?: boolean;
     readonly block?: boolean;
-    readonly children: readonly ReactElement<{value: string}>[];
+    readonly children: readonly ReactElement<TabItemProps>[];
     readonly defaultValue?: string;
     readonly values: readonly {value: string; label: string}[];
     readonly groupId?: string;

website/docs/markdown-features.mdx

@@ -296,6 +296,12 @@ And you will get the following:
   <TabItem value="banana">This is a banana 🍌</TabItem>
 </Tabs>
 
+:::info
+
+By default, tabs are rendered eagerly, but it is possible to load them lazily by passing the `lazy` prop to the `Tabs` component.
+
+:::
+
 ### Syncing tab choices
 
 You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Not that `groupID` are globally-namespaced.