@ceed/cds 1.22.3 → 1.22.5

package/dist/components/navigation/Tabs.md

@@ -1,8 +1,8 @@
 # Tabs
 
-## Introduction
+Tabs organize content into separate views where only one view is visible at a time. Users switch between views by selecting tab buttons, enabling efficient navigation within related content sections without leaving the current page. Built on Joy UI's Tabs, TabList, Tab, and TabPanel components, Tabs support horizontal and vertical orientations, multiple visual variants, semantic colors, and icon decorators.
 
-The Tabs component provides a way to organize content into separate views where only one view is visible at a time. Built on Joy UI's Tabs, TabList, Tab, and TabPanel components, it enables users to switch between different sections of related content without leaving the current page. Tabs are ideal for organizing related information that doesn't need to be viewed simultaneously.
+Tabs follow a composition pattern: the `Tabs` container manages state, `TabList` holds the tab buttons, `Tab` is each individual button, and `TabPanel` displays the content for the active tab.
 
 ```
 <Canvas of={Tabs.Playground} />
@@ -35,11 +35,11 @@ function MyComponent() {
 }
 ```
 
-## Examples
+## Features
 
 ### Basic Tabs
 
-Default tab navigation with horizontal layout.
+Default horizontal tab navigation with tab panels.
 
 ```tsx
 <Tabs {...args}>
@@ -62,7 +62,7 @@ Default tab navigation with horizontal layout.
 
 ### Variants
 
-Tabs support different visual styles through variants.
+Tabs support `plain`, `outlined`, `soft`, and `solid` visual styles. Apply the variant to both TabList and individual Tab components for a consistent appearance.
 
 ```
 <Canvas of={Tabs.Variants} />
@@ -70,7 +70,7 @@ Tabs support different visual styles through variants.
 
 ### Sizes
 
-Tabs come in different sizes to fit various use cases.
+Tabs come in `sm`, `md`, and `lg` sizes. Set the `size` prop on the Tabs container to affect all child components uniformly.
 
 ```
 <Canvas of={Tabs.Sizes} />
@@ -78,7 +78,7 @@ Tabs come in different sizes to fit various use cases.
 
 ### Colors
 
-Apply semantic colors to tabs.
+Apply semantic colors (`primary`, `neutral`, `success`, `warning`, `danger`) to individual tabs for color-coded navigation.
 
 ```
 <Canvas of={Tabs.Colors} />
@@ -86,7 +86,7 @@ Apply semantic colors to tabs.
 
 ### With Decorators
 
-Add icons or other elements to tab labels.
+Add icons or other elements before or after the tab label using `startDecorator` and `endDecorator` props.
 
 ```tsx
 <Tabs {...args}>
@@ -109,7 +109,7 @@ Add icons or other elements to tab labels.
 
 ### Vertical Orientation
 
-Tabs can be arranged vertically for sidebar-style navigation.
+Set `orientation="vertical"` on the Tabs container for sidebar-style navigation layouts.
 
 ```
 <Canvas of={Tabs.Vertical} />
@@ -117,7 +117,7 @@ Tabs can be arranged vertically for sidebar-style navigation.
 
 ### Disabled Tabs
 
-Individual tabs can be disabled while keeping others active.
+Individual tabs can be disabled with the `disabled` prop while keeping other tabs interactive.
 
 ```
 <Canvas of={Tabs.Disabled} />
@@ -125,32 +125,12 @@ Individual tabs can be disabled while keeping others active.
 
 ### Controlled Tabs
 
-Programmatically control the active tab.
+Use the `value` and `onChange` props for programmatic control of the active tab.
 
 ```
 <Canvas of={Tabs.Controlled} />
 ```
 
-## When to Use
-
-### ✅ Good Use Cases
-
-- **Related content sections**: When content can be logically grouped and users don't need to see all sections at once
-- **Settings pages**: Organizing different categories of settings (Profile, Security, Notifications)
-- **Dashboard views**: Switching between different data views or time periods
-- **Product details**: Showing Description, Specifications, Reviews as separate tabs
-- **Form sections**: Breaking long forms into logical steps (not for strict wizard flows)
-- **Code examples**: Showing code in different languages or frameworks
-
-### ❌ When Not to Use
-
-- **Primary navigation**: Use a navigation menu or sidebar for main app navigation
-- **Sequential workflows**: Use Stepper for multi-step processes that must be completed in order
-- **Comparing content**: If users need to see multiple sections simultaneously, use accordions or show all content
-- **Very few items**: If there are only 2 options, consider using a toggle or radio buttons
-- **Many items**: More than 5-6 tabs become hard to navigate; consider a dropdown or nested navigation
-- **Mobile layouts**: Consider alternative patterns like accordions or stacked sections on small screens
-
 ## Common Use Cases
 
 ### Settings Page
@@ -163,331 +143,92 @@ function SettingsPage() {
         <Tab startDecorator={<PersonIcon />}>Profile</Tab>
         <Tab startDecorator={<SecurityIcon />}>Security</Tab>
         <Tab startDecorator={<NotificationsIcon />}>Notifications</Tab>
-        <Tab startDecorator={<PaletteIcon />}>Appearance</Tab>
-      </TabList>
-      <TabPanel value={0}>
-        <ProfileSettings />
-      </TabPanel>
-      <TabPanel value={1}>
-        <SecuritySettings />
-      </TabPanel>
-      <TabPanel value={2}>
-        <NotificationSettings />
-      </TabPanel>
-      <TabPanel value={3}>
-        <AppearanceSettings />
-      </TabPanel>
-    </Tabs>
-  );
-}
-```
-
-### Product Detail Page
-
-```tsx
-function ProductDetails({ product }) {
-  return (
-    <Tabs defaultValue={0}>
-      <TabList>
-        <Tab>Description</Tab>
-        <Tab>Specifications</Tab>
-        <Tab>Reviews ({product.reviewCount})</Tab>
-        <Tab>Q&A</Tab>
       </TabList>
-      <TabPanel value={0}>
-        <Typography>{product.description}</Typography>
-      </TabPanel>
-      <TabPanel value={1}>
-        <SpecificationTable specs={product.specifications} />
-      </TabPanel>
-      <TabPanel value={2}>
-        <ReviewList reviews={product.reviews} />
-      </TabPanel>
-      <TabPanel value={3}>
-        <QASection productId={product.id} />
-      </TabPanel>
+      <TabPanel value={0}><ProfileSettings /></TabPanel>
+      <TabPanel value={1}><SecuritySettings /></TabPanel>
+      <TabPanel value={2}><NotificationSettings /></TabPanel>
     </Tabs>
   );
 }
 ```
 
-### Dashboard with Time Filters
+### Dashboard Time Range
 
 ```tsx
 function DashboardTabs() {
-  const [timeRange, setTimeRange] = useState('week');
+  const [range, setRange] = useState('week');
 
   return (
-    <Tabs value={timeRange} onChange={(e, val) => setTimeRange(val as string)}>
+    <Tabs value={range} onChange={(e, val) => setRange(val as string)}>
       <TabList>
         <Tab value="day">Today</Tab>
         <Tab value="week">This Week</Tab>
         <Tab value="month">This Month</Tab>
-        <Tab value="year">This Year</Tab>
       </TabList>
-      <TabPanel value="day">
-        <DailyStats />
-      </TabPanel>
-      <TabPanel value="week">
-        <WeeklyStats />
-      </TabPanel>
-      <TabPanel value="month">
-        <MonthlyStats />
-      </TabPanel>
-      <TabPanel value="year">
-        <YearlyStats />
-      </TabPanel>
+      <TabPanel value="day"><DailyStats /></TabPanel>
+      <TabPanel value="week"><WeeklyStats /></TabPanel>
+      <TabPanel value="month"><MonthlyStats /></TabPanel>
     </Tabs>
   );
 }
 ```
 
-### Code Examples
+### Vertical Sidebar
 
 ```tsx
-function CodeExamples() {
+function SidebarTabs() {
   return (
-    <Tabs defaultValue="react">
+    <Tabs orientation="vertical" defaultValue={0} sx={{ minWidth: 300 }}>
       <TabList>
-        <Tab value="react">React</Tab>
-        <Tab value="vue">Vue</Tab>
-        <Tab value="angular">Angular</Tab>
+        <Tab startDecorator={<DashboardIcon />}>Dashboard</Tab>
+        <Tab startDecorator={<AnalyticsIcon />}>Analytics</Tab>
+        <Tab startDecorator={<SettingsIcon />}>Settings</Tab>
       </TabList>
-      <TabPanel value="react">
-        <CodeBlock language="jsx">{reactCode}</CodeBlock>
-      </TabPanel>
-      <TabPanel value="vue">
-        <CodeBlock language="vue">{vueCode}</CodeBlock>
-      </TabPanel>
-      <TabPanel value="angular">
-        <CodeBlock language="typescript">{angularCode}</CodeBlock>
-      </TabPanel>
+      <TabPanel value={0}>Dashboard content</TabPanel>
+      <TabPanel value={1}>Analytics content</TabPanel>
+      <TabPanel value={2}>Settings content</TabPanel>
     </Tabs>
   );
 }
 ```
 
-### Vertical Sidebar Navigation
-
-```tsx
-function SidebarTabs() {
-  return (
-    <Box sx={{ display: 'flex' }}>
-      <Tabs orientation="vertical" defaultValue={0} sx={{ minWidth: 200 }}>
-        <TabList>
-          <Tab startDecorator={<DashboardIcon />}>Dashboard</Tab>
-          <Tab startDecorator={<AnalyticsIcon />}>Analytics</Tab>
-          <Tab startDecorator={<ReportsIcon />}>Reports</Tab>
-          <Tab startDecorator={<SettingsIcon />}>Settings</Tab>
-        </TabList>
-      </Tabs>
-      <Box sx={{ flex: 1, p: 2 }}>
-        <TabPanel value={0}>Dashboard content</TabPanel>
-        <TabPanel value={1}>Analytics content</TabPanel>
-        <TabPanel value={2}>Reports content</TabPanel>
-        <TabPanel value={3}>Settings content</TabPanel>
-      </Box>
-    </Box>
-  );
-}
-```
-
-## Component Structure
-
-Tabs uses a composition pattern with multiple sub-components:
-
-```tsx
-<Tabs>                    {/* Container - manages state */}
-  <TabList>               {/* Tab button container */}
-    <Tab>Tab 1</Tab>      {/* Individual tab buttons */}
-    <Tab>Tab 2</Tab>
-  </TabList>
-  <TabPanel value={0}>    {/* Content panels */}
-    Content 1
-  </TabPanel>
-  <TabPanel value={1}>
-    Content 2
-  </TabPanel>
-</Tabs>
-```
-
-## Props and Customization
-
-### Tabs Props
-
-| Prop           | Type                         | Default        | Description                         |
-| -------------- | ---------------------------- | -------------- | ----------------------------------- |
-| `defaultValue` | `string \| number`           | -              | Default selected tab (uncontrolled) |
-| `value`        | `string \| number`           | -              | Selected tab (controlled)           |
-| `onChange`     | `function`                   | -              | Callback when tab changes           |
-| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` | Tab layout direction                |
-| `size`         | `'sm' \| 'md' \| 'lg'`       | `'md'`         | Size of all child components        |
-
-### Tab Props
-
-| Prop             | Type                                                           | Default   | Description                        |
-| ---------------- | -------------------------------------------------------------- | --------- | ---------------------------------- |
-| `value`          | `string \| number`                                             | -         | Tab identifier (defaults to index) |
-| `variant`        | `'plain' \| 'outlined' \| 'soft' \| 'solid'`                   | `'plain'` | Visual style                       |
-| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | -         | Color scheme                       |
-| `disabled`       | `boolean`                                                      | `false`   | Disable the tab                    |
-| `startDecorator` | `ReactNode`                                                    | -         | Element before tab label           |
-| `endDecorator`   | `ReactNode`                                                    | -         | Element after tab label            |
-
-### TabPanel Props
-
-| Prop          | Type               | Default | Description                   |
-| ------------- | ------------------ | ------- | ----------------------------- |
-| `value`       | `string \| number` | -       | Matching tab value            |
-| `keepMounted` | `boolean`          | `false` | Keep panel in DOM when hidden |
-
-### Custom Styling
-
-```tsx
-<Tabs
-  sx={{
-    '--Tabs-gap': '8px',
-  }}
->
-  <TabList
-    sx={{
-      borderBottom: '1px solid',
-      borderColor: 'divider',
-    }}
-  >
-    <Tab
-      sx={{
-        '&.Mui-selected': {
-          borderBottom: '2px solid',
-          borderColor: 'primary.500',
-        },
-      }}
-    >
-      Custom Tab
-    </Tab>
-  </TabList>
-</Tabs>
-```
-
-## Accessibility
-
-Tabs components follow WAI-ARIA Tabs pattern for comprehensive accessibility:
-
-### ARIA Attributes
-
-- `role="tablist"` on TabList
-- `role="tab"` on each Tab
-- `role="tabpanel"` on each TabPanel
-- `aria-selected` indicates the active tab
-- `aria-controls` links tabs to their panels
-- `aria-labelledby` links panels to their tabs
-
-### Keyboard Navigation
-
-- **Tab**: Move focus to the tab list, then to the active panel
-- **Arrow Left/Right**: Move between tabs (horizontal orientation)
-- **Arrow Up/Down**: Move between tabs (vertical orientation)
-- **Home**: Move to first tab
-- **End**: Move to last tab
-- **Enter/Space**: Activate the focused tab
-
-### Screen Reader Support
-
-```tsx
-<Tabs aria-label="Account settings tabs">
-  <TabList>
-    <Tab>Profile</Tab>
-    <Tab>Security</Tab>
-  </TabList>
-  <TabPanel value={0}>
-    <h2 id="profile-heading">Profile Settings</h2>
-    {/* Content */}
-  </TabPanel>
-</Tabs>
-```
-
 ## Best Practices
 
-### ✅ Do
+- **Use clear, concise tab labels.** Each label should describe the content it reveals. Avoid generic names like "Tab 1" or "Other".
 
-1. **Use clear, concise labels**: Tab labels should clearly describe the content
+  ```tsx
+  {/* ✅ Good: Descriptive labels */}
+  <Tab>Account Settings</Tab>
+  <Tab>Notifications</Tab>
 
-```tsx
-// ✅ Good: Clear labels
-<Tab>Account Settings</Tab>
-<Tab>Notifications</Tab>
-
-// ❌ Bad: Vague labels
-<Tab>Tab 1</Tab>
-<Tab>Other</Tab>
-```
+  {/* ❌ Bad: Vague labels */}
+  <Tab>Tab 1</Tab>
+  <Tab>Other</Tab>
+  ```
 
-2. **Keep tab count manageable**: Limit to 5-6 tabs maximum
+- **Limit the number of tabs.** Aim for 3-6 tabs. More than 6 tabs become difficult to scan and navigate. If you need more sections, consider a sidebar navigation, nested navigation, or a different layout pattern.
 
-3. **Order tabs logically**: Place most important or frequently used tabs first
+- **Order tabs by importance.** Place the most frequently used or most important tab first. Users expect the default (leftmost or topmost) tab to contain the primary content.
 
-4. **Use consistent styling**: All tabs should have the same visual weight
+- **Do not use Tabs for sequential workflows.** Tabs are for parallel content sections that can be accessed in any order. For ordered multi-step processes, use a Stepper component instead.
 
-5. **Show active state clearly**: Users should always know which tab is selected
+  ```tsx
+  {/* ❌ Bad: Sequential steps as tabs */}
+  <Tab>Step 1: Info</Tab>
+  <Tab>Step 2: Payment</Tab>
+  <Tab>Step 3: Confirm</Tab>
 
-### ❌ Don't
+  {/* ✅ Good: Independent content sections */}
+  <Tab>Profile</Tab>
+  <Tab>Security</Tab>
+  <Tab>Billing</Tab>
+  ```
 
-1. **Don't hide critical information**: Important content shouldn't be buried in secondary tabs
+- **Keep styling consistent.** All tabs in a group should share the same variant and color. Mixing styles within the same TabList creates visual inconsistency.
 
-2. **Don't use for sequential processes**: Use Stepper for ordered workflows
-
-```tsx
-// ❌ Bad: Sequential steps as tabs
-<Tab>Step 1: Personal Info</Tab>
-<Tab>Step 2: Payment</Tab>
-<Tab>Step 3: Confirm</Tab>
-
-// ✅ Good: Use Stepper instead
-<Stepper activeStep={activeStep}>
-  <Step>Personal Info</Step>
-  <Step>Payment</Step>
-  <Step>Confirm</Step>
-</Stepper>
-```
-
-3. **Don't nest tabs within tabs**: Creates confusing navigation
-
-4. **Don't use inconsistent tab counts**: If tabs are dynamic, consider alternative UI patterns
-
-## Performance Considerations
-
-### Lazy Loading Tab Content
-
-By default, inactive tab panels are not rendered. For complex content, this provides automatic lazy loading:
-
-```tsx
-<TabPanel value={0}>
-  {/* Only rendered when this tab is active */}
-  <HeavyComponent />
-</TabPanel>
-```
-
-### Keep Mounted
-
-Use `keepMounted` when tab content needs to maintain state:
-
-```tsx
-<TabPanel value={0} keepMounted>
-  {/* Stays in DOM, maintains form state */}
-  <FormWithState />
-</TabPanel>
-```
-
-### Avoid Heavy Re-renders
-
-Memoize tab content when it depends on complex calculations:
-
-```tsx
-const tabContent = useMemo(() => (
-  <ExpensiveComponent data={data} />
-), [data]);
-
-<TabPanel value={0}>{tabContent}</TabPanel>
-```
+## Accessibility
 
-Tabs provide an intuitive way to organize related content while keeping the interface clean and navigable. Use them thoughtfully to enhance content discoverability without overwhelming users.
+- **WAI-ARIA Tabs pattern**: TabList receives `role="tablist"`, each Tab receives `role="tab"`, and each TabPanel receives `role="tabpanel"`. The `aria-selected`, `aria-controls`, and `aria-labelledby` attributes are set automatically.
+- **Keyboard navigation**: Arrow Left/Right moves between tabs in horizontal orientation. Arrow Up/Down moves between tabs in vertical orientation. Home jumps to the first tab, End to the last. Enter or Space activates the focused tab.
+- **Tab key behavior**: Pressing Tab from outside the tab list focuses the active tab. Pressing Tab again moves focus into the active panel content, not to the next tab button.
+- **Provide an accessible label**: Use `aria-label` on the Tabs container to give screen readers context for the tab group (e.g., `aria-label="Account settings"`).