From eb54d726d73a79323a3017d6edd1c67b8a08cc35 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 18 May 2025 22:34:19 +0100
Subject: [PATCH] Add docs for tabs

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .../src/app/(docs)/components/tabs/page.mdx   | 92 +++++++++++++++++++
 .../src/app/(docs)/components/tabs/props.ts   | 61 ++++++++++++
 canon-docs/src/snippets/stories-snippets.tsx  |  8 ++
 canon-docs/src/utils/data.ts                  |  5 +
 packages/canon/report.api.md                  | 10 +-
 .../src/components/Tabs/Tabs.stories.tsx      | 18 ++--
 packages/canon/src/components/Tabs/Tabs.tsx   |  3 +-
 packages/canon/src/components/Tabs/index.ts   |  2 +
 packages/canon/src/components/Tabs/types.ts   | 25 +++++
 9 files changed, 211 insertions(+), 13 deletions(-)
 create mode 100644 canon-docs/src/app/(docs)/components/tabs/page.mdx
 create mode 100644 canon-docs/src/app/(docs)/components/tabs/props.ts
 create mode 100644 packages/canon/src/components/Tabs/types.ts

diff --git a/canon-docs/src/app/(docs)/components/tabs/page.mdx b/canon-docs/src/app/(docs)/components/tabs/page.mdx
new file mode 100644
index 0000000000..478608d718
--- /dev/null
+++ b/canon-docs/src/app/(docs)/components/tabs/page.mdx
@@ -0,0 +1,92 @@
+import { PropsTable } from '@/components/PropsTable';
+import { TabsSnippet } from '@/snippets/stories-snippets';
+import { Snippet } from '@/components/Snippet';
+import { Tabs } from '@/components/Tabs';
+import { CodeBlock } from '@/components/CodeBlock';
+import {
+  tabsRootPropDefs,
+  tabsListPropDefs,
+  tabsTabPropDefs,
+  tabsPanelPropDefs,
+} from './props';
+import { BaseUI } from '@/components/HeadlessBanners/BaseUI';
+
+# Tabs
+
+A component for toggling between related panels on the same page.
+
+<Snippet
+  py={4}
+  preview={<TabsSnippet story="Default" />}
+  code={`<Tabs.Root>
+    <Tabs.List>
+      <Tabs.Tab>Tab 1</Tabs.Tab>
+      <Tabs.Tab>Tab 2</Tabs.Tab>
+      <Tabs.Tab>Tab 3 With long title</Tabs.Tab>
+    </Tabs.List>
+    <Tabs.Panel>Content for Tab 1</Tabs.Panel>
+    <Tabs.Panel>Content for Tab 2</Tabs.Panel>
+    <Tabs.Panel>Content for Tab 3</Tabs.Panel>
+  </Tabs.Root>`}
+/>
+
+<Tabs.Root>
+  <Tabs.List>
+    <Tabs.Tab>Usage</Tabs.Tab>
+    <Tabs.Tab>Theming</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel>
+    <CodeBlock
+      code={`import { Tabs } from '@backstage/canon';
+
+<Tabs.Root>
+    <Tabs.List>
+      <Tabs.Tab>Tab 1</Tabs.Tab>
+      <Tabs.Tab>Tab 2</Tabs.Tab>
+      <Tabs.Tab>Tab 3</Tabs.Tab>
+    </Tabs.List>
+    <Tabs.Panel>Content for Tab 1</Tabs.Panel>
+    <Tabs.Panel>Content for Tab 2</Tabs.Panel>
+    <Tabs.Panel>Content for Tab 3</Tabs.Panel>
+</Tabs.Root>
+`}
+    />
+  </Tabs.Panel>
+  <Tabs.Panel>
+    We recommend starting with our [global tokens](/theme/theming) to customize the library and align it with
+    your brand. For additional flexibility, you can use the provided class names for each element listed below.
+    - `canon-TabsRoot`
+    - `canon-TabsList`
+    - `canon-TabsTab`
+    - `canon-TabsPanel`
+    - `canon-TabsIndicator`
+  </Tabs.Panel>
+</Tabs.Root>
+
+## API reference
+
+<BaseUI href="https://base-ui.com/react/components/menu" />
+
+### Tabs.Root
+
+Groups the tabs and the corresponding panels. Renders a `<div>` element.
+
+<PropsTable data={tabsRootPropDefs} />
+
+### Tabs.List
+
+Groups the individual tab buttons. Renders a `<div>` element.
+
+<PropsTable data={tabsListPropDefs} />
+
+### Tabs.Tab
+
+An individual interactive tab button that toggles the corresponding panel. Renders a `<button>` element.
+
+<PropsTable data={tabsTabPropDefs} />
+
+### Tabs.Panel
+
+A panel displayed when the corresponding tab is active. Renders a `<div>` element.
+
+<PropsTable data={tabsPanelPropDefs} />
diff --git a/canon-docs/src/app/(docs)/components/tabs/props.ts b/canon-docs/src/app/(docs)/components/tabs/props.ts
new file mode 100644
index 0000000000..a966f17094
--- /dev/null
+++ b/canon-docs/src/app/(docs)/components/tabs/props.ts
@@ -0,0 +1,61 @@
+import {
+  childrenPropDefs,
+  classNamePropDefs,
+  stylePropDefs,
+} from '../../../../utils/propDefs';
+import type { PropDef } from '../../../../utils/propDefs';
+
+export const tabsRootPropDefs: Record<string, PropDef> = {
+  defaultValue: {
+    type: 'enum',
+    values: ['any'],
+    default: '0',
+  },
+  value: {
+    type: 'enum',
+    values: ['any'],
+  },
+  onValueChange: {
+    type: 'enum',
+    values: [`((value) => void)`],
+  },
+  ...childrenPropDefs,
+  ...classNamePropDefs,
+  ...stylePropDefs,
+};
+
+export const tabsListPropDefs: Record<string, PropDef> = {
+  activateOnFocus: {
+    type: 'boolean',
+    default: 'false',
+  },
+  loop: {
+    type: 'boolean',
+    default: 'false',
+  },
+  ...childrenPropDefs,
+  ...classNamePropDefs,
+  ...stylePropDefs,
+};
+
+export const tabsTabPropDefs: Record<string, PropDef> = {
+  value: {
+    type: 'string',
+  },
+  ...childrenPropDefs,
+  ...classNamePropDefs,
+  ...stylePropDefs,
+};
+
+export const tabsPanelPropDefs: Record<string, PropDef> = {
+  value: {
+    type: 'string',
+  },
+  keepMounted: {
+    type: 'boolean',
+    default: 'false',
+  },
+  ...childrenPropDefs,
+  ...classNamePropDefs,
+  ...stylePropDefs,
+};
diff --git a/canon-docs/src/snippets/stories-snippets.tsx b/canon-docs/src/snippets/stories-snippets.tsx
index 75ee2e31c3..64047ebde9 100644
--- a/canon-docs/src/snippets/stories-snippets.tsx
+++ b/canon-docs/src/snippets/stories-snippets.tsx
@@ -17,6 +17,7 @@ import * as MenuStories from '../../../packages/canon/src/components/Menu/Menu.s
 import * as LinkStories from '../../../packages/canon/src/components/Link/Link.stories';
 import * as AvatarStories from '../../../packages/canon/src/components/Avatar/Avatar.stories';
 import * as CollapsibleStories from '../../../packages/canon/src/components/Collapsible/Collapsible.stories';
+import * as TabsStories from '../../../packages/canon/src/components/Tabs/Tabs.stories';
 
 export const BoxSnippet = ({ story }: { story: keyof typeof BoxStories }) => {
   const stories = composeStories(BoxStories);
@@ -165,3 +166,10 @@ export const CollapsibleSnippet = ({
 
   return StoryComponent ? <StoryComponent /> : null;
 };
+
+export const TabsSnippet = ({ story }: { story: keyof typeof TabsStories }) => {
+  const stories = composeStories(TabsStories);
+  const StoryComponent = stories[story as keyof typeof stories];
+
+  return StoryComponent ? <StoryComponent /> : null;
+};
diff --git a/canon-docs/src/utils/data.ts b/canon-docs/src/utils/data.ts
index 891b057ad6..ba4fd5e432 100644
--- a/canon-docs/src/utils/data.ts
+++ b/canon-docs/src/utils/data.ts
@@ -121,6 +121,11 @@ export const components: Page[] = [
     slug: 'table',
     status: 'inProgress',
   },
+  {
+    title: 'Tabs',
+    slug: 'tabs',
+    status: 'alpha',
+  },
   {
     title: 'Text',
     slug: 'text',
diff --git a/packages/canon/report.api.md b/packages/canon/report.api.md
index 59a2e2bffd..674f47ccc3 100644
--- a/packages/canon/report.api.md
+++ b/packages/canon/report.api.md
@@ -1235,8 +1235,7 @@ export interface TableCellTextProps
 // @public (undocumented)
 export const Tabs: {
   Root: ForwardRefExoticComponent<
-    Omit<Tabs_2.Root.Props & RefAttributes<HTMLDivElement>, 'ref'> &
-      RefAttributes<HTMLDivElement>
+    TabsRootWithoutOrientation & RefAttributes<HTMLDivElement>
   >;
   List: ForwardRefExoticComponent<
     Omit<Tabs_2.List.Props & RefAttributes<HTMLDivElement>, 'ref'> &
@@ -1252,6 +1251,13 @@ export const Tabs: {
   >;
 };
 
+// @public (undocumented)
+export interface TabsRootWithoutOrientation
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof Tabs_2.Root>,
+    'orientation'
+  > {}
+
 // @public (undocumented)
 const Text_2: ForwardRefExoticComponent<
   TextProps & RefAttributes<HTMLParagraphElement>
diff --git a/packages/canon/src/components/Tabs/Tabs.stories.tsx b/packages/canon/src/components/Tabs/Tabs.stories.tsx
index ec8526e9b1..31945b1e02 100644
--- a/packages/canon/src/components/Tabs/Tabs.stories.tsx
+++ b/packages/canon/src/components/Tabs/Tabs.stories.tsx
@@ -16,7 +16,6 @@
 
 import type { Meta, StoryObj } from '@storybook/react';
 import { Tabs } from './Tabs';
-import { Text } from '../../index';
 
 const meta = {
   title: 'Components/Tabs',
@@ -26,6 +25,11 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+const panelStyles = {
+  padding: 'var(--canon-space-3)',
+  fontSize: 'var(--canon-font-size-2)',
+};
+
 export const Default: Story = {
   args: {
     children: (
@@ -35,15 +39,9 @@ export const Default: Story = {
           <Tabs.Tab>Tab 2</Tabs.Tab>
           <Tabs.Tab>Tab 3 With long title</Tabs.Tab>
         </Tabs.List>
-        <Tabs.Panel style={{ padding: 'var(--canon-space-3' }}>
-          <Text>Content for Tab 1</Text>
-        </Tabs.Panel>
-        <Tabs.Panel style={{ padding: 'var(--canon-space-3' }}>
-          <Text>Content for Tab 2</Text>
-        </Tabs.Panel>
-        <Tabs.Panel style={{ padding: 'var(--canon-space-3' }}>
-          <Text>Content for Tab 3</Text>
-        </Tabs.Panel>
+        <Tabs.Panel style={panelStyles}>Content for Tab 1</Tabs.Panel>
+        <Tabs.Panel style={panelStyles}>Content for Tab 2</Tabs.Panel>
+        <Tabs.Panel style={panelStyles}>Content for Tab 3</Tabs.Panel>
       </Tabs.Root>
     ),
   },
diff --git a/packages/canon/src/components/Tabs/Tabs.tsx b/packages/canon/src/components/Tabs/Tabs.tsx
index 116ef94fb9..b4f93a5b31 100644
--- a/packages/canon/src/components/Tabs/Tabs.tsx
+++ b/packages/canon/src/components/Tabs/Tabs.tsx
@@ -16,11 +16,12 @@
 
 import { forwardRef } from 'react';
 import { Tabs as TabsPrimitive } from '@base-ui-components/react/tabs';
+import type { TabsRootWithoutOrientation } from './types';
 import clsx from 'clsx';
 
 const TabsRoot = forwardRef<
   React.ElementRef<typeof TabsPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Root>
+  TabsRootWithoutOrientation
 >(({ className, ...props }, ref) => (
   <TabsPrimitive.Root
     ref={ref}
diff --git a/packages/canon/src/components/Tabs/index.ts b/packages/canon/src/components/Tabs/index.ts
index e9bc130d25..ba6ca91de7 100644
--- a/packages/canon/src/components/Tabs/index.ts
+++ b/packages/canon/src/components/Tabs/index.ts
@@ -13,4 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 export { Tabs } from './Tabs';
+export type { TabsRootWithoutOrientation } from './types';
diff --git a/packages/canon/src/components/Tabs/types.ts b/packages/canon/src/components/Tabs/types.ts
new file mode 100644
index 0000000000..f3b6342761
--- /dev/null
+++ b/packages/canon/src/components/Tabs/types.ts
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Tabs } from '@base-ui-components/react/tabs';
+
+// We are not supporting the orientation prop, so we need to omit it
+
+/** @public */
+export interface TabsRootWithoutOrientation
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof Tabs.Root>,
+    'orientation'
+  > {}