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.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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 jsdombeforeEach(() => {@@ -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(<XDSSelectordiff --git a/packages/core/src/Selector/XDSSelectorOption.tsx b/packages/core/src/Selector/XDSSelectorOption.tsxindex 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.tsxindex 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>({<XDSDropdownMenuItemkey={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>);