Skip to content

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

TypeScript

fix(topnav): render children as startContent (#2317)

Cindy Zhang3831519522a7
diff --git a/apps/storybook/stories/TopNav.stories.tsx b/apps/storybook/stories/TopNav.stories.tsx
index 7d1087875e..cc9cb9dd92 100644
--- a/apps/storybook/stories/TopNav.stories.tsx
+++ b/apps/storybook/stories/TopNav.stories.tsx
@@ -69,6 +69,18 @@ export const Default: Story = {
},
};
+export const ChildrenNavigationItems: Story = {
+ render: () => (
+ <XDSTopNav
+ label="Main navigation"
+ heading={<XDSTopNavHeading heading="Children Alias" />}>
+ <XDSTopNavItem label="Home" href="#" isSelected />
+ <XDSTopNavItem label="Products" href="#" />
+ <XDSTopNavItem label="About" href="#" />
+ </XDSTopNav>
+ ),
+};
+
export const WithLogo: Story = {
args: {
label: 'Main navigation',
diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsx
index e90af250c9..bbbe028e73 100644
--- a/packages/core/src/AppShell/XDSAppShell.test.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.test.tsx
@@ -22,6 +22,7 @@ import {render, screen, fireEvent} from '@testing-library/react';
import {XDSAppShell} from './XDSAppShell';
import {XDSMobileNav} from '../MobileNav';
import {XDSSideNav, XDSSideNavItem, XDSSideNavSection} from '../SideNav';
+import {XDSTopNav, XDSTopNavHeading, XDSTopNavItem} from '../TopNav';
// jsdom doesn't implement showModal/close on <dialog>, so we mock them
beforeAll(() => {
@@ -301,6 +302,34 @@ describe('XDSAppShell', () => {
expect(screen.getByRole('dialog', {hidden: true})).toBeInTheDocument();
});
+ it('keeps TopNav children in the combined mobile drawer with sideNav content', () => {
+ mockMql = createMockMatchMedia(true);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+ render(
+ <XDSAppShell
+ topNav={
+ <XDSTopNav
+ label="Navigation"
+ heading={<XDSTopNavHeading heading="App" />}>
+ <XDSTopNavItem label="Home" href="/" />
+ </XDSTopNav>
+ }
+ sideNav={<TestSideNav>Side item</TestSideNav>}>
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+
+ expect(
+ screen.getByRole('button', {name: /open navigation/i}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getAllByRole('dialog', {hidden: true}).length,
+ ).toBeGreaterThan(0);
+ expect(screen.getByText('Home')).toBeInTheDocument();
+ expect(screen.getAllByText('Side item').length).toBeGreaterThan(0);
+ });
+
it('renders mobile layout on first render when defaultIsMobile is true', () => {
// matchMedia says mobile too — simulates correct SSR hint
mockMql = createMockMatchMedia(true);
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index ddde2c8a1f..05fa6d6690 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -26,7 +26,7 @@ export const docs = {
components: [
{
name: 'XDSTopNav',
- description: 'Main navigation bar container with slot-based layout.',
+ description: 'Main navigation bar container with slot-based layout. Children are accepted as an alias for startContent.',
props: [
{
name: 'heading',
@@ -42,6 +42,13 @@ export const docs = {
'Start content slot for navigation items or breadcrumbs — positioned after the heading, left-aligned.',
slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Alias for startContent. Prefer startContent when composing with heading, centerContent, or endContent; children keeps the common React nav-item pattern from silently dropping items.',
+ slotElements: [{__element: 'XDSTopNavItem', props: {label: 'Home', href: '#'}}],
+ },
{
name: 'centerContent',
type: 'ReactNode',
@@ -409,7 +416,7 @@ export const docsZh = {
components: [
{
name: 'XDSTopNav',
- description: '采用插槽式布局的主导航栏容器。',
+ description: '采用插槽式布局的主导航栏容器。children 可作为 startContent 的别名。',
props: [
{
name: 'heading',
@@ -423,6 +430,12 @@ export const docsZh = {
description:
'起始内容插槽,用于导航项或面包屑 — 位于标题之后,左对齐。',
},
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'startContent 的别名。与 heading、centerContent 或 endContent 组合时优先使用 startContent;children 可避免常见 React 导航项写法被静默丢弃。',
+ },
{
name: 'centerContent',
type: 'ReactNode',
@@ -777,10 +790,11 @@ export const docsDense = {
components: [
{
name: 'XDSTopNav',
- description: 'Main nav bar container w/ slot-based layout.',
+ description: 'Main nav bar container w/ slot-based layout; children alias startContent.',
propDescriptions: {
heading: 'Heading slot (logo, brand) at left edge.',
startContent: 'Nav items/breadcrumbs after heading, left-aligned.',
+ children: 'Alias for startContent; prefer startContent with other slots.',
centerContent: 'Center slot (tabs, search); switches to 3-column CSS grid for true centering.',
endContent: 'Search/icons/profile at right edge.',
label: 'A11y label for nav landmark, aria-label on <nav>.',
diff --git a/packages/core/src/TopNav/XDSTopNav.test.tsx b/packages/core/src/TopNav/XDSTopNav.test.tsx
index 702cd0d04b..e1de32283f 100644
--- a/packages/core/src/TopNav/XDSTopNav.test.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.test.tsx
@@ -60,6 +60,29 @@ describe('XDSTopNav', () => {
expect(screen.getByTestId('start-content')).toBeInTheDocument();
});
+ it('renders children as startContent', () => {
+ render(
+ <XDSTopNav>
+ <XDSTopNavItem label="Home" href="/" />
+ <XDSTopNavItem label="About" href="/about" />
+ </XDSTopNav>,
+ );
+
+ expect(screen.getByRole('link', {name: 'Home'})).toBeInTheDocument();
+ expect(screen.getByRole('link', {name: 'About'})).toBeInTheDocument();
+ });
+
+ it('prefers startContent when both startContent and children are provided', () => {
+ render(
+ <XDSTopNav startContent={<XDSTopNavItem label="Start" href="/start" />}>
+ <XDSTopNavItem label="Child" href="/child" />
+ </XDSTopNav>,
+ );
+
+ expect(screen.getByRole('link', {name: 'Start'})).toBeInTheDocument();
+ expect(screen.queryByRole('link', {name: 'Child'})).not.toBeInTheDocument();
+ });
+
it('renders endContent slot', () => {
render(
<XDSTopNav endContent={<span data-testid="end-content">Actions</span>} />,
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 9f3dcbb13c..4649c0bec7 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -4,7 +4,7 @@
/**
* @file XDSTopNav.tsx
- * @input Uses React, HTMLAttributes, ReactNode
+ * @input Uses React, ReactNode
* @output Exports XDSTopNav component and XDSTopNavProps
* @position Core implementation; consumed by index.ts
*
@@ -123,6 +123,14 @@ export interface XDSTopNavProps extends XDSBaseProps<HTMLElement> {
* Positioned after the title, left-aligned.
*/
startContent?: ReactNode;
+ /**
+ * Alias for startContent. Prefer startContent when composing with other slots.
+ *
+ * This keeps the common React children pattern from silently dropping
+ * navigation items. If both children and startContent are provided,
+ * startContent takes precedence and children are ignored.
+ */
+ children?: ReactNode;
/**
* Center content slot - typically tabs, search bar, or primary navigation.
* Positioned at the horizontal center of the nav bar.
@@ -146,8 +154,10 @@ export interface XDSTopNavProps extends XDSBaseProps<HTMLElement> {
* Top navigation bar for application headers.
*
* Slot-based layout with `heading`, `startContent`, `centerContent`, and
- * `endContent`. When `centerContent` is provided, the layout switches to a
- * three-column CSS grid to keep center content horizontally centered.
+ * `endContent`. `children` are accepted as an alias for `startContent`
+ * so navigation items do not silently disappear when using the common
+ * React children pattern. When `centerContent` is provided, the layout switches
+ * to a three-column CSS grid to keep center content horizontally centered.
*
* @example
* ```
@@ -162,6 +172,7 @@ export interface XDSTopNavProps extends XDSBaseProps<HTMLElement> {
export function XDSTopNav({
heading,
startContent,
+ children,
centerContent,
endContent,
label,
@@ -174,8 +185,10 @@ export function XDSTopNav({
const renderMode = useXDSTopNavRenderMode();
const mobileContent = useXDSTopNavMobileContent();
const {hasAutoToggle} = useXDSAppShellMobile();
+ const resolvedStartContent = startContent ?? children;
const hasCenterContent = centerContent != null;
- const hasCollapsibleContent = startContent != null || centerContent != null;
+ const hasCollapsibleContent =
+ resolvedStartContent != null || centerContent != null;
// Show mobile toggle when there's ANY drawer content — own items OR SideNav via context
const hasMobileDrawerContent = hasCollapsibleContent || mobileContent != null;
@@ -220,7 +233,7 @@ export function XDSTopNav({
<XDSMobileNav header={heading}>
{hasCollapsibleContent && (
<div {...stylex.props(styles.drawerItems)}>
- {startContent}
+ {resolvedStartContent}
{centerContent}
</div>
)}
@@ -260,9 +273,11 @@ export function XDSTopNav({
{...props}>
<div {...stylex.props(styles.leftSection)}>
{heading && <div {...stylex.props(styles.heading)}>{heading}</div>}
- {startContent && (
+ {resolvedStartContent && (
<XDSTopNavSlotContext value="start">
- <div {...stylex.props(styles.startContent)}>{startContent}</div>
+ <div {...stylex.props(styles.startContent)}>
+ {resolvedStartContent}
+ </div>
</XDSTopNavSlotContext>
)}
</div>