update tabs docs and stories

Author: missating

packages/circuit-ui/components/Tabs/Tabs.mdx

@@ -19,7 +19,8 @@ The Tabs component allows users to navigate between different views or sections
 
 ### Group related content
 
-Tabs help optimize space by organizing large amounts of content into easily scannable sections, reducing cognitive load for users. They provide simple navigation between related sections that don’t require side-by-side comparison.
+Tabs help optimize space by organizing large amounts of content into easily scannable sections, reducing cognitive load for users.
+They provide simple navigation between related sections that don’t require side-by-side comparison.
 
 Examples include:
 
@@ -45,66 +46,40 @@ You can use the Tabs component out of the box to create a tabbed view by providi
 
 ### Use subcomponents independently
 
-If you need finer control over your layout, you can use the `Tab`, `TabList`, and `TabPanel` components independently. This gives you flexibility to customize the structure and behavior of your tabs while still relying on the core functionality provided by Tabs.
+For finer control over layout, use `TabList` and `TabPanel` independently. Pass your tabs via the `tabs` prop.
+`TabList` manages selection state, keyboard navigation, and accessibility attributes internally. Use the `onTabChange` callback to track which panel to show.
 
-⚠️ When doing so, you are responsible for ensuring accessibility and managing state correctly.
+- Using `TabList`:
+  - Provide a `tabs` array with a unique `id` and label for each tab.
+  - Use `onTabChange` to receive the selected tab's id and toggle panel visibility.
+- Using `TabPanel`:
+  - Assign a unique `id` following the `panel-{id}` convention to match `TabList`'s `aria-controls`.
+  - Set `aria-labelledby` to `tab-{id}` to reference the corresponding tab.
 
-- Using Tab:
-  - Provide a unique `id` for each tab.
-  - Add an `aria-controls` attribute that points to the id of its corresponding panel.
-  - Implement keyboard navigation (e.g., arrow keys, Home/End) to support keyboard users, or use the `useTabState` helper [hook](#usetabstate) to manage state and interactions. This is not necessary for [tab-like navigation](#tab-like-navigation).
-- Using TabPanel:
-  - Assign a unique id to each panel.
-  - Ensure this id matches the `aria-controls` value of its corresponding tab.
-  - Set `aria-labelledby` to reference the id of the associated tab.
-
-<Story of={Stories.ControlledState} />
+<Story of={Stories.WithTabPanel} />
 
 #### useTabState
 
-Use this hook to manage tab state and handle user interactions. The hook accepts an array of tab IDs and an optional initially selected index, and returns:
-- `selectedId` : the id of the currently selected tab.
-- `onTabKeyDown` : an `onKeyDown` handler for your Tab component that manages arrow-key navigation and updates selectedId.
-- `onTabClick` : an `onClick` handler for your Tab component that updates selectedId when a tab is clicked.
+If you need even finer control and want to build a fully custom tab implementation, `useTabState` is available as a standalone hook.
+It accepts an array of tab IDs and an optional initially selected index, and returns `selectedId`, an `onTabKeyDown` handler for arrow-key navigation, and an `onTabClick` handler for click selection.
 
 ```tsx
-import {useTabState} from '@sumup-oss/circuit-ui';
-
-const {
-    selectedId,
-    onTabKeyDown,
-    onTabClick,
-  } = useTabState(
-    ['tab-1', 'tab-2', 'tab-3'],
-    2,
-  );
+import { useTabState } from "@sumup-oss/circuit-ui";
+
+const { selectedId, onTabKeyDown, onTabClick } = useTabState(
+  ["tab-1", "tab-2", "tab-3"],
+  2
+);
 ```
 
 ### Tab-like navigation
 
-If you need to implement a tab-like navigation rather than true tab semantics, you can control the rendering behavior of the TabList and Tab components to achieve this.
-- Set the `as` prop of Tablist to `"navigation"` to render a native `<nav>` containing an element with the role `list` to wrap its children.
-- Set the `as` prop of Tab component to `"listitem"` to wrap your tab in an element with role `listitem`.
+If you need to implement a tab-like navigation rather than true tab semantics, set the `as` prop of `TabList` to `"navigation"`. This renders a native `<nav>` containing an element with the role `list` to wrap its children.
 
-The components would render styled to look like tabs but without any tab ARIA roles. This ensures a correctly structured and accessible navigation pattern that visually matches the tab design.
-
-```tsx
-<TabList as="navigation">
-  <Tab as="listitem" href="/home">Home</Tab>
-  <Tab as="listitem" href="/about">About</Tab>
-  <Tab as="listitem" href="/contact">Contact</Tab>
-</TabList>
-```
+The component renders styled to look like tabs but without any tab ARIA roles. This ensures a correctly structured and accessible navigation pattern that visually matches the tab design.
 
 <Story of={TabListStories.Navigation} />
 
-### With links
-
-Tabs render as buttons by default. In navigation contexts, you can pass a `href` prop to render them as links.
-Avoid using external links, as this can create an inconsistent user experience across tabs. Instead, place the external link outside the Tabs component to maintain predictable behavior.
-
-<Story of={Stories.Links} />
-
 ### Stretched
 
 Set the `stretched` prop to true to make all tabs expand and share the available space evenly.

packages/circuit-ui/components/Tabs/Tabs.stories.tsx

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+import { useState } from 'react';
+
 import { ArrowLeft, ExternalLink } from '@sumup-oss/icons';
 
 import { Body } from '../Body/index.js';
@@ -24,7 +26,6 @@ import type { TabsProps } from './Tabs.js';
 import { Tabs } from './Tabs.js';
 import { TabList } from './components/TabList/TabList.js';
 import { TabPanel } from './components/TabPanel/TabPanel.js';
-import { Tab } from './components/Tab/Tab.js';
 import { action } from 'storybook/actions';
 
 export default {
@@ -120,28 +121,30 @@ Stretched.args = {
   stretched: true,
 };
 
-export const Links = () => (
-  <TabList>
-    <Tab selected>Home</Tab>
-    <Tab href="#posts" target="">
-      Posts
-    </Tab>
-    <Tab href="#reviews">Reviews</Tab>
-  </TabList>
-);
+export const WithTabPanel = () => {
+  const items = tabs.slice(0, 3);
+  const [selectedId, setSelectedId] = useState(items[0].id);
 
-Links.parameters = {
-  controls: { hideNoControlsWarning: true },
+  return (
+    <div>
+      <TabList
+        tabs={items.map(({ id, tab }) => ({ id, tab }))}
+        onTabChange={setSelectedId}
+      />
+      {items.map(({ id, panel }) => (
+        <TabPanel
+          key={id}
+          id={`panel-${id}`}
+          aria-labelledby={`tab-${id}`}
+          hidden={selectedId !== id}
+        >
+          {panel}
+        </TabPanel>
+      ))}
+    </div>
+  );
 };
 
-export const WithTabChangeCallback = () => (
-  <Tabs
-    items={tabs.slice(0, 3)}
-    onTabChange={action('Changed to tab with id:')}
-  />
-);
-
-WithTabChangeCallback.storyName = 'With TabChange';
-WithTabChangeCallback.parameters = {
+WithTabPanel.parameters = {
   controls: { hideNoControlsWarning: true },
 };

packages/circuit-ui/index.ts

@@ -124,8 +124,6 @@ export type {
 
 export { Tabs } from './components/Tabs/Tabs.js';
 export type { TabsProps } from './components/Tabs/Tabs.js';
-export { Tab } from './components/Tabs/components/Tab/Tab.js';
-export type { TabProps } from './components/Tabs/components/Tab/Tab.js';
 export { TabPanel } from './components/Tabs/components/TabPanel/TabPanel.js';
 export type { TabPanelProps } from './components/Tabs/components/TabPanel/TabPanel.js';
 export { TabList } from './components/Tabs/components/TabList/TabList.js';