Skip to content

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

TypeScript

feat(core): add item endContent slots (#2802)

Cindy Zhang2c2a68b637be
diff --git a/.changeset/dropdown-menu-item-endcontent.md b/.changeset/dropdown-menu-item-endcontent.md
new file mode 100644
index 0000000000..0ec3f70e99
--- /dev/null
+++ b/.changeset/dropdown-menu-item-endcontent.md
@@ -0,0 +1,8 @@
+---
+'@xds/core': minor
+'@xds/cli': patch
+---
+
+`XDSDropdownMenuItem`, `XDSContextMenuItem`, and `XDSSelectorOption` now use `endContent` for trailing badges, status icons, shortcuts, and other end-aligned content. The previous trailing-content `children` prop has been removed while the package is still prerelease.
+
+`xds upgrade` includes `migrate-item-children-to-endcontent`, which moves `<XDSDropdownMenuItem>...</XDSDropdownMenuItem>`, `<XDSContextMenuItem>...</XDSContextMenuItem>`, `<XDSSelectorOption>...</XDSSelectorOption>`, and `children={...}` usage to `endContent={...}`.
diff --git a/packages/cli/src/codemods/transforms/v0.0.15/__tests__/migrate-item-children-to-endcontent.test.mjs b/packages/cli/src/codemods/transforms/v0.0.15/__tests__/migrate-item-children-to-endcontent.test.mjs
new file mode 100644
index 0000000000..e97f812f29
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.15/__tests__/migrate-item-children-to-endcontent.test.mjs
@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../migrate-item-children-to-endcontent.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const file = {source, path: 'test.tsx'};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('migrate-item-children-to-endcontent', () => {
+ it('moves a JSX child to endContent', async () => {
+ const input = `<XDSDropdownMenuItem label="Notifications">
+ <XDSBadge label={3} />
+</XDSDropdownMenuItem>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('endContent={<XDSBadge label={3} />}');
+ expect(output).toContain('/>');
+ expect(output).not.toContain('</XDSDropdownMenuItem>');
+ });
+
+ it('moves an expression child on XDSContextMenuItem to endContent', async () => {
+ const input = `<XDSContextMenuItem label="Auto">
+ {isSelected && <CheckIcon />}
+</XDSContextMenuItem>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('endContent={isSelected && <CheckIcon />}');
+ expect(output).not.toContain('</XDSContextMenuItem>');
+ });
+
+ it('moves text children to endContent', async () => {
+ const input = `<XDSDropdownMenuItem label="Status">New</XDSDropdownMenuItem>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('endContent="New"');
+ });
+
+ it('wraps multiple meaningful children in a fragment', async () => {
+ const input = `<XDSDropdownMenuItem label="Shortcut">
+ <XDSBadge label="New" />
+ <XDSKbd keys="⌘K" />
+</XDSDropdownMenuItem>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('endContent={<>');
+ expect(output).toContain('<XDSBadge label="New" />');
+ expect(output).toContain('<XDSKbd keys="⌘K" />');
+ });
+
+ it('moves XDSSelectorOption children to endContent', async () => {
+ const input = `<XDSSelectorOption label="Admin">
+ <XDSBadge label="Owner" />
+</XDSSelectorOption>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('endContent={<XDSBadge label="Owner" />}');
+ expect(output).not.toContain('</XDSSelectorOption>');
+ });
+
+ it('renames an explicit children prop to endContent', async () => {
+ const input = `<XDSSelectorOption label="Notifications" children={<XDSBadge label={3} />} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('endContent={<XDSBadge label={3} />}');
+ expect(output).not.toContain('children=');
+ });
+
+ it('does not touch an item that already uses endContent', async () => {
+ const input = `<XDSDropdownMenuItem label="Notifications" endContent={<XDSBadge label={3} />} />`;
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('skips ambiguous items with both children and endContent', async () => {
+ const input = `<XDSDropdownMenuItem label="Notifications" endContent={<NewBadge />}>
+ <OldBadge />
+</XDSDropdownMenuItem>`;
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('returns undefined when no changes are needed', async () => {
+ const {default: transform} = await import(
+ '../migrate-item-children-to-endcontent.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const source = `<XDSDropdownMenuItem label="Edit" />`;
+ const result = transform({source, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.0.15/index.mjs b/packages/cli/src/codemods/transforms/v0.0.15/index.mjs
index 20efb3f4a9..ebbc312982 100644
--- a/packages/cli/src/codemods/transforms/v0.0.15/index.mjs
+++ b/packages/cli/src/codemods/transforms/v0.0.15/index.mjs
@@ -22,6 +22,10 @@ import renameStackElementToAs, {
meta as renameStackElementToAsMeta,
} from './rename-stack-element-to-as.mjs';
+import migrateItemChildrenToEndContent, {
+ meta as migrateItemChildrenToEndContentMeta,
+} from './migrate-item-children-to-endcontent.mjs';
+
export default [
{
name: 'rename-date-picker-to-input',
@@ -43,4 +47,9 @@ export default [
transform: renameStackElementToAs,
meta: renameStackElementToAsMeta,
},
+ {
+ name: 'migrate-item-children-to-endcontent',
+ transform: migrateItemChildrenToEndContent,
+ meta: migrateItemChildrenToEndContentMeta,
+ },
];
diff --git a/packages/cli/src/codemods/transforms/v0.0.15/migrate-item-children-to-endcontent.mjs b/packages/cli/src/codemods/transforms/v0.0.15/migrate-item-children-to-endcontent.mjs
new file mode 100644
index 0000000000..cb380f42ed
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.15/migrate-item-children-to-endcontent.mjs
@@ -0,0 +1,129 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Migrate item children → endContent
+ *
+ * XDSDropdownMenuItem, XDSContextMenuItem, and XDSSelectorOption trailing
+ * slots were renamed from `children` to `endContent` to match other list-like
+ * components.
+ *
+ * Handles:
+ * 1. JSX children: <XDSDropdownMenuItem>...</XDSDropdownMenuItem>
+ * → <XDSDropdownMenuItem endContent={...} />
+ * 2. The same migration for XDSContextMenuItem and XDSSelectorOption
+ * 3. Explicit children prop: <XDSSelectorOption children={...} />
+ * → <XDSSelectorOption endContent={...} />
+ *
+ * Skips elements that already have `endContent`, because merging the old and
+ * new slots is ambiguous.
+ */
+
+const COMPONENT_NAMES = new Set([
+ 'XDSDropdownMenuItem',
+ 'XDSContextMenuItem',
+ 'XDSSelectorOption',
+]);
+
+export const meta = {
+ title: 'Migrate item children → endContent',
+ description:
+ 'Moves trailing content on `XDSDropdownMenuItem`, `XDSContextMenuItem`, and `XDSSelectorOption` from deprecated `children` usage to the `endContent` prop.',
+};
+
+function isWhitespaceText(node) {
+ return node.type === 'JSXText' && node.value.trim() === '';
+}
+
+function isEmptyExpression(node) {
+ return (
+ node.type === 'JSXExpressionContainer' &&
+ node.expression.type === 'JSXEmptyExpression'
+ );
+}
+
+function getMeaningfulChildren(children) {
+ return children.filter(
+ child => !isWhitespaceText(child) && !isEmptyExpression(child),
+ );
+}
+
+function createEndContentValue(j, children) {
+ if (children.length === 0) {
+ return null;
+ }
+
+ if (children.length === 1) {
+ const child = children[0];
+
+ if (child.type === 'JSXText') {
+ const text = child.value.trim();
+ return text === '' ? null : j.stringLiteral(text);
+ }
+
+ if (child.type === 'JSXExpressionContainer') {
+ return j.jsxExpressionContainer(child.expression);
+ }
+
+ if (child.type === 'JSXElement' || child.type === 'JSXFragment') {
+ return j.jsxExpressionContainer(child);
+ }
+ }
+
+ return j.jsxExpressionContainer(
+ j.jsxFragment(j.jsxOpeningFragment(), j.jsxClosingFragment(), children),
+ );
+}
+
+function getJSXAttribute(openingElement, name) {
+ return openingElement.attributes.find(
+ attr => attr.type === 'JSXAttribute' && attr.name.name === name,
+ );
+}
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ root.find(j.JSXElement).forEach(path => {
+ const elementName = path.node.openingElement.name;
+ if (
+ elementName.type !== 'JSXIdentifier' ||
+ !COMPONENT_NAMES.has(elementName.name)
+ ) {
+ return;
+ }
+ const {openingElement} = path.node;
+ const endContentAttr = getJSXAttribute(openingElement, 'endContent');
+ const childrenAttr = getJSXAttribute(openingElement, 'children');
+
+ if (childrenAttr != null) {
+ if (endContentAttr != null) {
+ return;
+ }
+ childrenAttr.name.name = 'endContent';
+ hasChanges = true;
+ return;
+ }
+
+ if (endContentAttr != null) {
+ return;
+ }
+
+ const meaningfulChildren = getMeaningfulChildren(path.node.children ?? []);
+ const endContentValue = createEndContentValue(j, meaningfulChildren);
+ if (endContentValue == null) {
+ return;
+ }
+
+ openingElement.attributes.push(
+ j.jsxAttribute(j.jsxIdentifier('endContent'), endContentValue),
+ );
+ openingElement.selfClosing = true;
+ path.node.children = [];
+ path.node.closingElement = null;
+ hasChanges = true;
+ });
+
+ return hasChanges ? root.toSource() : undefined;
+}
diff --git a/packages/core/src/ContextMenu/ContextMenuItem.doc.mjs b/packages/core/src/ContextMenu/ContextMenuItem.doc.mjs
index 55a1e3e643..9e4479bc00 100644
--- a/packages/core/src/ContextMenu/ContextMenuItem.doc.mjs
+++ b/packages/core/src/ContextMenu/ContextMenuItem.doc.mjs
@@ -25,7 +25,7 @@ export const docs = {
description: 'Secondary description text displayed below the label.',
},
{
- name: 'children',
+ name: 'endContent',
type: 'ReactNode',
description: 'Additional content rendered after the label and description.',
},
@@ -59,7 +59,7 @@ export const docsZh = {
description: '显示在标签下方的次要描述文本。',
},
{
- name: 'children',
+ name: 'endContent',
type: 'ReactNode',
description: '在标签和描述之后渲染的附加内容。',
},
@@ -80,7 +80,7 @@ export const docsDense = {
icon: 'icon before label',
label: 'primary label text',
description: 'secondary text below label',
- children: 'additional content after label+description',
+ endContent: 'additional content after label+description',
xstyle: 'StyleX styles for root container',
},
};
diff --git a/packages/core/src/ContextMenu/XDSContextMenu.test.tsx b/packages/core/src/ContextMenu/XDSContextMenu.test.tsx
index d61ac89998..48c4b8104b 100644
--- a/packages/core/src/ContextMenu/XDSContextMenu.test.tsx
+++ b/packages/core/src/ContextMenu/XDSContextMenu.test.tsx
@@ -12,6 +12,7 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {XDSContextMenu} from './XDSContextMenu';
+import {XDSContextMenuItem} from './index';
import {XDSDropdownMenuItem} from '../DropdownMenu/XDSDropdownMenuItem';
import {XDSDivider} from '../Divider';
@@ -241,6 +242,23 @@ describe('XDSContextMenu compound mode', () => {
).toBeInTheDocument();
});
+ it('renders XDSContextMenuItem endContent', () => {
+ render(
+ <XDSContextMenu
+ menuContent={
+ <XDSContextMenuItem
+ label="Cut"
+ endContent={<span data-testid="shortcut">⌘X</span>}
+ onClick={() => {}}
+ />
+ }>
+ <div>Right-click me</div>
+ </XDSContextMenu>,
+ );
+
+ expect(screen.getByTestId('shortcut')).toHaveTextContent('⌘X');
+ });
+
it('calls onClick when compound item is clicked', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
diff --git a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
index 3fff805dde..5821a52f1a 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
@@ -25,7 +25,7 @@ export const docs = {
description: 'Secondary description text displayed below the label.',
},
{
- name: 'children',
+ name: 'endContent',
type: 'ReactNode',
description: 'Additional content rendered after the label and description.',
},
@@ -59,7 +59,7 @@ export const docsZh = {
description: '显示在标签下方的次要描述文本。',
},
{
- name: 'children',
+ name: 'endContent',
type: 'ReactNode',
description: '在标签和描述之后渲染的附加内容。',
},
@@ -80,7 +80,7 @@ export const docsDense = {
icon: 'icon before label',
label: 'primary label text',
description: 'secondary text below label',
- children: 'additional content after label+description',
+ endContent: 'additional content after label+description',
xstyle: 'StyleX styles for root container',
},
};
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
index b2eb76df84..b9ca8e0bb7 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
@@ -486,6 +486,19 @@ describe('XDSDropdownMenu compound mode', () => {
).toBeInTheDocument();
});
+ it('renders endContent after the item label', () => {
+ render(
+ <XDSDropdownMenu button={{label: 'Actions'}}>
+ <XDSDropdownMenuItem
+ label="Notifications"
+ endContent={<span data-testid="badge">3</span>}
+ />
+ </XDSDropdownMenu>,
+ );
+
+ expect(screen.getByTestId('badge')).toHaveTextContent('3');
+ });
+
it('calls onClick when compound item is clicked', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
index 8b2f58e9e2..c0c3223912 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
@@ -16,6 +16,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+ * - /packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
* - /packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
* - /packages/core/src/DropdownMenu/index.ts
* - /apps/storybook/stories/DropdownMenu.stories.tsx
@@ -86,7 +87,7 @@ export interface XDSDropdownMenuItemProps {
/** Whether the item is disabled. @default false */
isDisabled?: boolean;
/** Additional content to render after the label/description. */
- children?: ReactNode;
+ endContent?: ReactNode;
/**
* StyleX styles for layout customization (margins, positioning, sizing).
* Must be a `stylex.create()` value — not an inline style object.
@@ -114,7 +115,7 @@ export interface XDSDropdownMenuItemProps {
* ```
* <XDSDropdownMenu button={{ label: 'Actions' }}>
* <XDSDropdownMenuItem icon={PencilIcon} label="Edit" onClick={handleEdit} />
- * <XDSDropdownMenuItem label="Delete" onClick={handleDelete} isDisabled />
+ * <XDSDropdownMenuItem label="Delete" endContent={<XDSBadge label="⌘D" />} onClick={handleDelete} />
* </XDSDropdownMenu>
* ```
*/
@@ -124,7 +125,7 @@ export function XDSDropdownMenuItem({
description,
onClick,
isDisabled = false,
- children,
+ endContent,
xstyle,
className,
style,
@@ -151,7 +152,7 @@ export function XDSDropdownMenuItem({
}
label={label}
description={description}
- endContent={children}
+ endContent={endContent}
onClick={handleClick}
isDisabled={isDisabled}
xstyle={[
diff --git a/packages/core/src/Selector/SelectorOption.doc.mjs b/packages/core/src/Selector/SelectorOption.doc.mjs
index b7c33ad280..5ae4411b69 100644
--- a/packages/core/src/Selector/SelectorOption.doc.mjs
+++ b/packages/core/src/Selector/SelectorOption.doc.mjs
@@ -25,6 +25,11 @@ export const docs = {
type: 'ReactNode',
description: 'Secondary description text displayed below the label.',
},
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Additional content rendered after the label and description.',
+ },
],
};
@@ -50,6 +55,11 @@ export const docsZh = {
type: 'ReactNode',
description: '显示在标签下方的次要描述文本。',
},
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '在标签和描述之后渲染的附加内容。',
+ },
],
};
@@ -62,5 +72,6 @@ export const docsDense = {
label: 'Primary label text for item.',
icon: 'Icon displayed before label.',
description: 'Secondary description text below label.',
+ endContent: 'Additional content after label+description.',
},
};
diff --git a/packages/core/src/Selector/XDSSelector.test.tsx b/packages/core/src/Selector/XDSSelector.test.tsx
index bfbdc2b84e..46bc511286 100644
--- a/packages/core/src/Selector/XDSSelector.test.tsx
+++ b/packages/core/src/Selector/XDSSelector.test.tsx
@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {XDSSelector} from './XDSSelector';
+import {XDSSelectorOption} from './XDSSelectorOption';
// Mock showPopover and hidePopover methods since they're not implemented in jsdom
beforeEach(() => {
@@ -125,6 +126,27 @@ describe('XDSSelector', () => {
expect(screen.getByRole('combobox')).toHaveTextContent('Banana');
});
+ it('renders custom option endContent', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSSelector
+ label="Role"
+ options={[{value: 'admin', label: 'Admin'}]}
+ value={undefined}
+ onChange={() => {}}>
+ {option => (
+ <XDSSelectorOption
+ label={option.label}
+ endContent={<span data-testid="option-badge">Owner</span>}
+ />
+ )}
+ </XDSSelector>,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ expect(screen.getByTestId('option-badge')).toHaveTextContent('Owner');
+ });
+
it('supports explicit menu placement', () => {
render(
<XDSSelector
diff --git a/packages/core/src/Selector/XDSSelectorOption.tsx b/packages/core/src/Selector/XDSSelectorOption.tsx
index b6b81b57c9..634f584d66 100644
--- a/packages/core/src/Selector/XDSSelectorOption.tsx
+++ b/packages/core/src/Selector/XDSSelectorOption.tsx
@@ -43,7 +43,7 @@ export interface XDSSelectorOptionProps {
/**
* Additional content to render after the label/description.
*/
- children?: ReactNode;
+ endContent?: ReactNode;
/**
* StyleX styles created via `stylex.create()`. Merged with the component's
@@ -95,7 +95,7 @@ export function XDSSelectorOption({
icon,
label,
description,
- children,
+ endContent,
xstyle,
className,
style,
@@ -109,7 +109,7 @@ export function XDSSelectorOption({
}
label={label}
description={description}
- endContent={children}
+ endContent={endContent}
xstyle={[embeddedStyles.root, xstyle]}
{...mergeProps(xdsThemeProps('selector-option'), {className, style})}
/>
diff --git a/packages/lab/src/Schedule/plugins/ViewSelectorPlugin.tsx b/packages/lab/src/Schedule/plugins/ViewSelectorPlugin.tsx
index 0f2f2e4caf..58db94c330 100644
--- a/packages/lab/src/Schedule/plugins/ViewSelectorPlugin.tsx
+++ b/packages/lab/src/Schedule/plugins/ViewSelectorPlugin.tsx
@@ -57,11 +57,13 @@ function XDSScheduleViewSelectorControl<View extends XDSScheduleViewBase>({
<XDSDropdownMenuItem
key={option.label}
label={option.label}
- onClick={() => onChangeView?.(option.view)}>
- {index === selectedIndex ? (
- <XDSIcon icon="check" size="sm" color="primary" />
- ) : null}
- </XDSDropdownMenuItem>
+ onClick={() => onChangeView?.(option.view)}
+ endContent={
+ index === selectedIndex ? (
+ <XDSIcon icon="check" size="sm" color="primary" />
+ ) : null
+ }
+ />
))}
</XDSDropdownMenu>
);