Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve TabList docs page and block examples (#1646)

Ernest67662ec3da66
diff --git a/packages/cli/templates/blocks/components/TabList/TabListTabsWithActions.doc.mjs b/packages/cli/templates/blocks/components/TabList/TabListTabsWithActions.doc.mjs
index 435d797af0..6843e44faa 100644
--- a/packages/cli/templates/blocks/components/TabList/TabListTabsWithActions.doc.mjs
+++ b/packages/cli/templates/blocks/components/TabList/TabListTabsWithActions.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'TabList — With Actions',
description:
- 'Page header pattern with tabs on the left and action buttons pushed to the right.',
+ 'Page header pattern with tabs on the left and action buttons pushed to the right. When hasDivider is true, pair with a smaller button size (sm) so actions don\u2019t overpower the tab row.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['TabList', 'Tab', 'Button'],
diff --git a/packages/cli/templates/blocks/components/TabList/TabListTabsWithBadge.doc.mjs b/packages/cli/templates/blocks/components/TabList/TabListTabsWithBadge.doc.mjs
new file mode 100644
index 0000000000..93faa7f6e7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TabList/TabListTabsWithBadge.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TabList \u2014 With Badge',
+ description:
+ 'Tabs with notification badge counts rendered via endContent. Uses error variant for urgent counts and neutral for informational ones.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['TabList', 'Tab', 'Badge'],
+};
diff --git a/packages/cli/templates/blocks/components/TabList/TabListTabsWithBadge.tsx b/packages/cli/templates/blocks/components/TabList/TabListTabsWithBadge.tsx
new file mode 100644
index 0000000000..1cd0cc63e3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TabList/TabListTabsWithBadge.tsx
@@ -0,0 +1,24 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTabList, XDSTab} from '@xds/core/TabList';
+import {XDSBadge} from '@xds/core/Badge';
+
+export default function TabListTabsWithBadge() {
+ const [value, setValue] = useState('inbox');
+ return (
+ <XDSTabList value={value} onChange={setValue}>
+ <XDSTab
+ value="inbox"
+ label="Inbox"
+ endContent={<XDSBadge variant="error" label="5" />}
+ />
+ <XDSTab value="sent" label="Sent" />
+ <XDSTab
+ value="drafts"
+ label="Drafts"
+ endContent={<XDSBadge variant="neutral" label="2" />}
+ />
+ </XDSTabList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TabList/TabListTabsWithStatusDot.doc.mjs b/packages/cli/templates/blocks/components/TabList/TabListTabsWithStatusDot.doc.mjs
new file mode 100644
index 0000000000..c62cf8f640
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TabList/TabListTabsWithStatusDot.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TabList \u2014 With Status Dot',
+ description:
+ 'Tabs with status dot indicators rendered via endContent to show live environment health at a glance.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['TabList', 'Tab', 'StatusDot'],
+};
diff --git a/packages/cli/templates/blocks/components/TabList/TabListTabsWithStatusDot.tsx b/packages/cli/templates/blocks/components/TabList/TabListTabsWithStatusDot.tsx
new file mode 100644
index 0000000000..087574ab44
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TabList/TabListTabsWithStatusDot.tsx
@@ -0,0 +1,24 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTabList, XDSTab} from '@xds/core/TabList';
+import {XDSStatusDot} from '@xds/core/StatusDot';
+
+export default function TabListTabsWithStatusDot() {
+ const [value, setValue] = useState('production');
+ return (
+ <XDSTabList value={value} onChange={setValue}>
+ <XDSTab
+ value="production"
+ label="Production"
+ endContent={<XDSStatusDot variant="positive" label="Healthy" />}
+ />
+ <XDSTab
+ value="staging"
+ label="Staging"
+ endContent={<XDSStatusDot variant="warning" label="Degraded" />}
+ />
+ <XDSTab value="development" label="Development" />
+ </XDSTabList>
+ );
+}
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 51246cc450..8cc473d311 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -113,8 +113,8 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
- {guidance: false, description: 'Use for page-level navigation — use Tabs instead.'},
- {guidance: false, description: 'Use for simple on/off states — use ToggleButton instead.'},
+ {guidance: false, description: 'Use for page-level navigation — use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
+ {guidance: false, description: 'Use for simple on/off states — use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
],
},
};
@@ -155,8 +155,8 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
- {guidance: false, description: 'Use for page-level navigation — use Tabs instead.'},
- {guidance: false, description: 'Use for simple on/off states — use ToggleButton instead.'},
+ {guidance: false, description: 'Use for page-level navigation — use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
+ {guidance: false, description: 'Use for simple on/off states — use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
],
},
};
@@ -169,8 +169,8 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
- {guidance: false, description: 'Use for page-level navigation — use Tabs instead.'},
- {guidance: false, description: 'Use for simple on/off states — use ToggleButton instead.'},
+ {guidance: false, description: 'Use for page-level navigation — use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
+ {guidance: false, description: 'Use for simple on/off states — use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index e13dad10c3..a18da1b713 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -99,6 +99,12 @@ export const docs = {
description:
'Icon element shown when the tab is selected; falls back to icon if not provided.',
},
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description:
+ 'Content rendered after the label, such as a badge count or status dot.',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -134,8 +140,10 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
{ guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+ { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
{ guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
{ guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
+ { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
],
anatomy: [
{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
@@ -245,6 +253,12 @@ export const docsZh = {
description:
'标签选中时显示的图标元素;未提供时回退到 icon。',
},
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description:
+ '在标签文本之后渲染的内容,例如徽章计数或状态点。',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -280,8 +294,10 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
{ guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+ { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
{ guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
{ guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
+ { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
],
anatomy: [
{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
@@ -300,8 +316,10 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
{ guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+ { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
{ guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
{ guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
+ { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
],
anatomy: [
{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
@@ -332,6 +350,7 @@ export const docsDense = {
as: 'Custom link component overriding XDSLinkProvider; only w/ href.',
icon: 'Icon shown when not selected.',
selectedIcon: 'Icon shown when selected; falls back to icon.',
+ endContent: 'Content after the label (badge, status dot, etc.).',
xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
},
},
diff --git a/packages/core/src/TabList/XDSTab.tsx b/packages/core/src/TabList/XDSTab.tsx
index 365d368e9d..a52351a815 100644
--- a/packages/core/src/TabList/XDSTab.tsx
+++ b/packages/core/src/TabList/XDSTab.tsx
@@ -60,6 +60,10 @@ export interface XDSTabProps extends XDSBaseProps<HTMLButtonElement> {
* Icon element shown when tab is selected. Falls back to `icon` if not provided.
*/
selectedIcon?: ReactNode;
+ /**
+ * Content rendered after the label (e.g. a badge or status dot).
+ */
+ endContent?: ReactNode;
}
// =============================================================================
@@ -158,6 +162,11 @@ const styles = stylex.create({
pointerEvents: 'none',
fontWeight: fontWeightVars['--font-weight-semibold'],
},
+ endContentWrapper: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ flexShrink: 0,
+ },
});
const sizeStyles = stylex.create({
@@ -205,6 +214,7 @@ export function XDSTab({
href,
icon,
selectedIcon,
+ endContent,
xstyle,
className,
style,
@@ -279,12 +289,17 @@ export function XDSTab({
</span>
);
+ const endContentElement = endContent ? (
+ <span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
+ ) : null;
+
if (href != null) {
return (
<LinkComponent href={href} onClick={handleSelect} {...sharedProps}>
{hoverBgElement}
{iconElement}
{labelElement}
+ {endContentElement}
{indicatorElement}
</LinkComponent>
);
@@ -295,6 +310,7 @@ export function XDSTab({
{hoverBgElement}
{iconElement}
{labelElement}
+ {endContentElement}
{indicatorElement}
</button>
);
diff --git a/packages/core/src/TabList/XDSTabList.test.tsx b/packages/core/src/TabList/XDSTabList.test.tsx
index d848ae7f33..910083ab4f 100644
--- a/packages/core/src/TabList/XDSTabList.test.tsx
+++ b/packages/core/src/TabList/XDSTabList.test.tsx
@@ -189,6 +189,51 @@ describe('XDSTabList', () => {
expect(screen.getByTestId('icon')).toBeInTheDocument();
expect(screen.queryByTestId('selected-icon')).not.toBeInTheDocument();
});
+
+ it('renders endContent after the label', () => {
+ render(
+ <XDSTabList value="home" onChange={() => {}}>
+ <XDSTab
+ value="home"
+ label="Home"
+ endContent={<span data-testid="badge">5</span>}
+ />
+ </XDSTabList>,
+ );
+
+ expect(screen.getByTestId('badge')).toBeInTheDocument();
+ expect(screen.getByTestId('badge').textContent).toBe('5');
+ });
+
+ it('does not render endContent wrapper when endContent is not provided', () => {
+ const {container} = render(
+ <XDSTabList value="home" onChange={() => {}}>
+ <XDSTab value="home" label="Home" />
+ </XDSTabList>,
+ );
+
+ // The endContentWrapper span should not exist
+ const button = screen.getByRole('button', {name: 'Home'});
+ // Button children: hoverBg, labelContainer, indicator (no endContent wrapper)
+ const spans = button.querySelectorAll(':scope > span');
+ // hoverBg + labelContainer + indicator = 3 spans
+ expect(spans.length).toBe(3);
+ });
+
+ it('renders endContent in link tabs', () => {
+ render(
+ <XDSTabList value="home" onChange={() => {}}>
+ <XDSTab
+ value="home"
+ label="Home"
+ href="/home"
+ endContent={<span data-testid="dot">●</span>}
+ />
+ </XDSTabList>,
+ );
+
+ expect(screen.getByTestId('dot')).toBeInTheDocument();
+ });
});
describe('XDSTab polymorphic link', () => {