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.mjsindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.mjsindex 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.tsxindex 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.tsxindex 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', () => {