docs(tabs): add docs for reusable TabList/Tab/TabPanel

Author: maiieul

apps/website/src/components/mdx-components/index.tsx

@@ -159,9 +159,10 @@ export const components: Record<string, any> = {
   }),
   AnatomyTable,
   APITable,
+  CodeSnippet,
+  InstallSnippet,
   KeyboardInteractionTable,
+  Note,
   StatusBanner,
   Showcase,
-  CodeSnippet,
-  InstallSnippet,
 };

apps/website/src/routes/docs/headless/tabs/examples/reusable.tsx

@@ -0,0 +1,62 @@
+import { Slot, component$ } from '@builder.io/qwik';
+import {
+  Tab,
+  TabList,
+  TabListProps,
+  TabPanel,
+  TabPanelProps,
+  TabProps,
+  Tabs,
+  TabsProps,
+} from '@qwik-ui/headless';
+
+const CustomTabs = (props: TabsProps) => (
+  <Tabs {...props} TabList={CustomTabList} Tab={CustomTab} TabPanel={CustomTabPanel} />
+);
+
+const CustomTabList = component$<TabListProps>(() => {
+  return (
+    <TabList>
+      <Slot />
+    </TabList>
+  );
+});
+
+const CustomTab = component$<TabProps>(({ ...props }) => {
+  return (
+    <Tab {...props}>
+      <span class="text-red-500">Custom</span> <Slot />
+    </Tab>
+  );
+});
+
+const CustomTabPanel = component$<TabPanelProps>(({ ...props }) => {
+  return (
+    <TabPanel {...props}>
+      <span class="text-red-500">Description:</span> <Slot />
+    </TabPanel>
+  );
+});
+
+export default component$(() => {
+  return (
+    <div class="tabs-example mr-auto">
+      <CustomTabs>
+        <CustomTabList>
+          <CustomTab>Tab 1</CustomTab>
+          <CustomTab>Tab 2</CustomTab>
+          <CustomTab>Tab 3</CustomTab>
+        </CustomTabList>
+        <CustomTabPanel>
+          <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
+        </CustomTabPanel>
+        <CustomTabPanel>
+          <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
+        </CustomTabPanel>
+        <CustomTabPanel>
+          <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
+        </CustomTabPanel>
+      </CustomTabs>
+    </div>
+  );
+});

apps/website/src/routes/docs/headless/tabs/index.mdx

@@ -85,6 +85,27 @@ You can pass a custom `onClick$` handler.
 
 <Showcase name="on-click" />
 
+## Creating reusable Tabs
+
+In order to remove the need for a linking `value` prop for each Tab and TabPanel pair, we have chosen to create the Tabs component as an [inline component](https://qwik.builder.io/docs/components/overview/#inline-components).
+
+By consequence, the Tabs component needs to be aware of its children. If you want to create your custom reusable TabList/Tab/TabPanel components, you will have to pass them to the Tabs component through its `TabList`, `Tab`, and `TabPanel` props:
+
+```tsx
+const CustomTabs = (props: TabsProps) => (
+  <Tabs {...props} TabList={CustomTabList} Tab={CustomTab} TabPanel={CustomTabPanel} />
+);
+```
+
+<br />
+
+<Note status="warning">
+  If you don't do the above, the Tabs component cannot know if your CustomTab component is
+  a Tab component.
+</Note>
+
+<Showcase name="reusable" />
+
 ## Accessibility
 
 ### Keyboard interaction