Skip to content

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

TypeScript

feat(codemods): add heading rename codemods, fix SideNav doc (#530)

Cindy Zhange6810723d6da
diff --git a/packages/cli/src/codemods/transforms/v0.0.2/__tests__/rename-sidenav-header-to-heading.test.mjs b/packages/cli/src/codemods/transforms/v0.0.2/__tests__/rename-sidenav-header-to-heading.test.mjs
new file mode 100644
index 0000000000..a9d6cb8b20
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.2/__tests__/rename-sidenav-header-to-heading.test.mjs
@@ -0,0 +1,138 @@
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../rename-sidenav-header-to-heading.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const file = {source, path: 'test.tsx'};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('rename-sidenav-header-to-heading', () => {
+ it('renames title to heading on XDSSideNavHeader', async () => {
+ const input = '<XDSSideNavHeader title="My App" />';
+ const output = await applyTransform(input);
+ expect(output).toContain('heading="My App"');
+ expect(output).not.toContain('title=');
+ });
+
+ it('renames all props on XDSSideNavHeader', async () => {
+ const input = `<XDSSideNavHeader
+ title="My App"
+ titleHref="/"
+ supertitle="Acme Corp"
+ supertitleHref="/org"
+ subtitle="v2.0"
+ subtitleHref="/version"
+/>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('heading="My App"');
+ expect(output).toContain('headingHref="/"');
+ expect(output).toContain('superheading="Acme Corp"');
+ expect(output).toContain('superheadingHref="/org"');
+ expect(output).toContain('subheading="v2.0"');
+ expect(output).toContain('subheadingHref="/version"');
+ expect(output).not.toContain('title=');
+ expect(output).not.toContain('titleHref=');
+ expect(output).not.toContain('supertitle=');
+ expect(output).not.toContain('supertitleHref=');
+ expect(output).not.toContain('subtitle=');
+ expect(output).not.toContain('subtitleHref=');
+ });
+
+ it('renames props on XDSSideNavHeading (already renamed component)', async () => {
+ const input = '<XDSSideNavHeading title="My App" titleHref="/" />';
+ const output = await applyTransform(input);
+ expect(output).toContain('heading="My App"');
+ expect(output).toContain('headingHref="/"');
+ });
+
+ it('renames <XDSSideNavHeader> to <XDSSideNavHeading>', async () => {
+ const input = '<XDSSideNavHeader title="My App" />';
+ const output = await applyTransform(input);
+ expect(output).toContain('<XDSSideNavHeading');
+ expect(output).not.toContain('XDSSideNavHeader');
+ });
+
+ it('renames closing tag for XDSSideNavHeader', async () => {
+ const input = '<XDSSideNavHeader title="My App"><Menu /></XDSSideNavHeader>';
+ const output = await applyTransform(input);
+ expect(output).toContain('<XDSSideNavHeading');
+ expect(output).toContain('</XDSSideNavHeading>');
+ expect(output).not.toContain('XDSSideNavHeader');
+ });
+
+ it('renames XDSSideNavHeader in import specifiers', async () => {
+ const input = `import {XDSSideNavHeader} from '@xds/core';
+<XDSSideNavHeader title="My App" />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('import {XDSSideNavHeading}');
+ expect(output).not.toContain('XDSSideNavHeader');
+ });
+
+ it('renames XDSSideNavHeaderProps in import specifiers', async () => {
+ const input = `import {XDSSideNavHeaderProps} from '@xds/core';`;
+ const output = await applyTransform(input);
+ expect(output).toContain('XDSSideNavHeadingProps');
+ expect(output).not.toContain('XDSSideNavHeaderProps');
+ });
+
+ it('does not rename props on non-target components', async () => {
+ const input = '<XDSCard title="Card Title" subtitle="Subtitle" />';
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('does not rename props on other XDS components', async () => {
+ const input = '<XDSSideNavSection title="Section" />';
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('preserves non-renamed props', async () => {
+ const input = '<XDSSideNavHeader title="My App" icon={<AppIcon />} menu={<Menu />} />';
+ const output = await applyTransform(input);
+ expect(output).toContain('heading="My App"');
+ expect(output).toContain('icon={<AppIcon />}');
+ expect(output).toContain('menu={<Menu />}');
+ });
+
+ it('returns undefined when no changes needed', async () => {
+ const {default: transform} = await import(
+ '../rename-sidenav-header-to-heading.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const source = '<XDSSideNavHeading heading="My App" headingHref="/" />';
+ const result = transform({source, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+
+ it('handles all renames in one file', async () => {
+ const input = `import {XDSSideNavHeader} from '@xds/core';
+<XDSSideNavHeader
+ title="My App"
+ titleHref="/"
+ supertitle="Corp"
+ subtitle="v1"
+ icon={<Icon />}
+/>`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('XDSSideNavHeader');
+ expect(output).toContain('XDSSideNavHeading');
+ expect(output).toContain('heading="My App"');
+ expect(output).toContain('headingHref="/"');
+ expect(output).toContain('superheading="Corp"');
+ expect(output).toContain('subheading="v1"');
+ });
+
+ it('handles aliased imports', async () => {
+ const input = `import {XDSSideNavHeader as Header} from '@xds/core';
+<Header title="My App" />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('XDSSideNavHeading as Header');
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.0.2/__tests__/rename-topnav-title-to-heading.test.mjs b/packages/cli/src/codemods/transforms/v0.0.2/__tests__/rename-topnav-title-to-heading.test.mjs
new file mode 100644
index 0000000000..48ff3dba01
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.2/__tests__/rename-topnav-title-to-heading.test.mjs
@@ -0,0 +1,114 @@
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../rename-topnav-title-to-heading.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const file = {source, path: 'test.tsx'};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('rename-topnav-title-to-heading', () => {
+ it('renames title to heading on XDSTopNav', async () => {
+ const input = '<XDSTopNav title={<Logo />} label="Nav" />';
+ const output = await applyTransform(input);
+ expect(output).toContain('heading={<Logo />}');
+ expect(output).not.toContain('title=');
+ });
+
+ it('renames title to heading on XDSTopNavTitle', async () => {
+ const input = '<XDSTopNavTitle title="My App" href="/" />';
+ const output = await applyTransform(input);
+ expect(output).toContain('heading="My App"');
+ expect(output).not.toContain('title=');
+ });
+
+ it('renames title to heading on XDSTopNavHeading', async () => {
+ const input = '<XDSTopNavHeading title="My App" href="/" />';
+ const output = await applyTransform(input);
+ expect(output).toContain('heading="My App"');
+ expect(output).not.toContain('title=');
+ });
+
+ it('renames <XDSTopNavTitle> to <XDSTopNavHeading>', async () => {
+ const input = '<XDSTopNavTitle title="My App" href="/" />';
+ const output = await applyTransform(input);
+ expect(output).toContain('<XDSTopNavHeading');
+ expect(output).not.toContain('XDSTopNavTitle');
+ });
+
+ it('renames closing tag for XDSTopNavTitle', async () => {
+ const input = '<XDSTopNavTitle title="My App">Custom</XDSTopNavTitle>';
+ const output = await applyTransform(input);
+ expect(output).toContain('<XDSTopNavHeading');
+ expect(output).toContain('</XDSTopNavHeading>');
+ expect(output).not.toContain('XDSTopNavTitle');
+ });
+
+ it('renames XDSTopNavTitle in import specifiers', async () => {
+ const input = `import {XDSTopNavTitle} from '@xds/core';
+<XDSTopNavTitle title="My App" />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('import {XDSTopNavHeading}');
+ expect(output).not.toContain('XDSTopNavTitle');
+ });
+
+ it('renames XDSTopNavTitleProps in import specifiers', async () => {
+ const input = `import {XDSTopNavTitleProps} from '@xds/core';`;
+ const output = await applyTransform(input);
+ expect(output).toContain('XDSTopNavHeadingProps');
+ expect(output).not.toContain('XDSTopNavTitleProps');
+ });
+
+ it('does not rename title on non-target components', async () => {
+ const input = '<XDSBanner title="Alert" />';
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('does not rename title on other XDS components', async () => {
+ const input = '<XDSDialog title="Confirm" />';
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('preserves other props on XDSTopNav', async () => {
+ const input = '<XDSTopNav title={<Logo />} label="Nav" startContent={items} />';
+ const output = await applyTransform(input);
+ expect(output).toContain('heading={<Logo />}');
+ expect(output).toContain('label="Nav"');
+ expect(output).toContain('startContent={items}');
+ });
+
+ it('returns undefined when no changes needed', async () => {
+ const {default: transform} = await import(
+ '../rename-topnav-title-to-heading.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const source = '<XDSTopNav heading={<Logo />} label="Nav" />';
+ const result = transform({source, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+
+ it('handles all renames in one file', async () => {
+ const input = `import {XDSTopNav, XDSTopNavTitle} from '@xds/core';
+<XDSTopNav title={<XDSTopNavTitle title="My App" href="/" />} label="Nav" />`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('XDSTopNavTitle');
+ expect(output).not.toContain('title=');
+ expect(output).toContain('XDSTopNavHeading');
+ expect(output).toContain('heading=');
+ });
+
+ it('handles aliased imports', async () => {
+ const input = `import {XDSTopNavTitle as Title} from '@xds/core';
+<Title title="My App" />`;
+ const output = await applyTransform(input);
+ // Import should rename imported but keep local alias
+ expect(output).toContain('XDSTopNavHeading as Title');
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.0.2/index.mjs b/packages/cli/src/codemods/transforms/v0.0.2/index.mjs
index dac7362ce6..59699e0697 100644
--- a/packages/cli/src/codemods/transforms/v0.0.2/index.mjs
+++ b/packages/cli/src/codemods/transforms/v0.0.2/index.mjs
@@ -22,6 +22,12 @@ import renameFormTooltipStartIcon, {
import renameIsShownToIsOpen, {
meta as isShownMeta,
} from './rename-isShown-to-isOpen.mjs';
+import renameTopNavTitleToHeading, {
+ meta as topNavTitleMeta,
+} from './rename-topnav-title-to-heading.mjs';
+import renameSideNavHeaderToHeading, {
+ meta as sideNavHeaderMeta,
+} from './rename-sidenav-header-to-heading.mjs';
export default [
{
name: 'rename-selector-items-to-options',
@@ -53,4 +59,14 @@ export default [
transform: renameIsShownToIsOpen,
meta: isShownMeta,
},
+ {
+ name: 'rename-topnav-title-to-heading',
+ transform: renameTopNavTitleToHeading,
+ meta: topNavTitleMeta,
+ },
+ {
+ name: 'rename-sidenav-header-to-heading',
+ transform: renameSideNavHeaderToHeading,
+ meta: sideNavHeaderMeta,
+ },
];
diff --git a/packages/cli/src/codemods/transforms/v0.0.2/rename-sidenav-header-to-heading.mjs b/packages/cli/src/codemods/transforms/v0.0.2/rename-sidenav-header-to-heading.mjs
new file mode 100644
index 0000000000..8a9ba2ac23
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.2/rename-sidenav-header-to-heading.mjs
@@ -0,0 +1,82 @@
+/**
+ * @file Codemod: Rename XDSSideNavHeader → XDSSideNavHeading, rename props
+ * @see https://github.com/facebookexperimental/xds/pull/527
+ *
+ * - Renames props on XDSSideNavHeader and XDSSideNavHeading:
+ * title → heading, titleHref → headingHref,
+ * supertitle → superheading, supertitleHref → superheadingHref,
+ * subtitle → subheading, subtitleHref → subheadingHref
+ * - Renames <XDSSideNavHeader> to <XDSSideNavHeading> (JSX element name)
+ * - Renames XDSSideNavHeader to XDSSideNavHeading in import specifiers
+ * - Renames XDSSideNavHeaderProps to XDSSideNavHeadingProps in type imports
+ */
+
+export const meta = {
+ title:
+ 'Rename SideNav header → heading, XDSSideNavHeader → XDSSideNavHeading',
+ description:
+ 'Renames props (title → heading, titleHref → headingHref, supertitle → superheading, etc.) on XDSSideNavHeader/XDSSideNavHeading, renames the component, and updates import specifiers.',
+ pr: '#527',
+};
+
+const TARGET_COMPONENTS = new Set([
+ 'XDSSideNavHeader',
+ 'XDSSideNavHeading',
+]);
+
+const PROP_RENAMES = {
+ title: 'heading',
+ titleHref: 'headingHref',
+ supertitle: 'superheading',
+ supertitleHref: 'superheadingHref',
+ subtitle: 'subheading',
+ subtitleHref: 'subheadingHref',
+};
+
+const IMPORT_RENAMES = {
+ XDSSideNavHeader: 'XDSSideNavHeading',
+ XDSSideNavHeaderProps: 'XDSSideNavHeadingProps',
+};
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ // 1. Rename props on target components
+ root.find(j.JSXOpeningElement).forEach((path) => {
+ const name = path.node.name;
+ if (name.type !== 'JSXIdentifier' || !TARGET_COMPONENTS.has(name.name)) {
+ return;
+ }
+
+ path.node.attributes.forEach((attr) => {
+ if (attr.type === 'JSXAttribute' && attr.name.name in PROP_RENAMES) {
+ attr.name.name = PROP_RENAMES[attr.name.name];
+ hasChanges = true;
+ }
+ });
+ });
+
+ // 2. Rename <XDSSideNavHeader> to <XDSSideNavHeading> (opening and closing tags)
+ root.find(j.JSXIdentifier, {name: 'XDSSideNavHeader'}).forEach((path) => {
+ path.node.name = 'XDSSideNavHeading';
+ hasChanges = true;
+ });
+
+ // 3. Rename import specifiers
+ root.find(j.ImportSpecifier).forEach((path) => {
+ const imported = path.node.imported;
+ if (imported.type === 'Identifier' && imported.name in IMPORT_RENAMES) {
+ const oldName = imported.name;
+ const newName = IMPORT_RENAMES[oldName];
+ imported.name = newName;
+ if (path.node.local && path.node.local.name === oldName) {
+ path.node.local.name = newName;
+ }
+ hasChanges = true;
+ }
+ });
+
+ return hasChanges ? root.toSource() : undefined;
+}
diff --git a/packages/cli/src/codemods/transforms/v0.0.2/rename-topnav-title-to-heading.mjs b/packages/cli/src/codemods/transforms/v0.0.2/rename-topnav-title-to-heading.mjs
new file mode 100644
index 0000000000..fb47664b3e
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.2/rename-topnav-title-to-heading.mjs
@@ -0,0 +1,71 @@
+/**
+ * @file Codemod: Rename XDSTopNavTitle → XDSTopNavHeading, title → heading
+ * @see https://github.com/facebookexperimental/xds/pull/527
+ *
+ * - Renames `title` prop to `heading` on XDSTopNav, XDSTopNavTitle, and XDSTopNavHeading
+ * - Renames <XDSTopNavTitle> to <XDSTopNavHeading> (JSX element name)
+ * - Renames XDSTopNavTitle to XDSTopNavHeading in import specifiers
+ * - Renames XDSTopNavTitleProps to XDSTopNavHeadingProps in type imports
+ */
+
+export const meta = {
+ title: 'Rename TopNav title → heading, XDSTopNavTitle → XDSTopNavHeading',
+ description:
+ 'Renames the `title` prop to `heading` on XDSTopNav and XDSTopNavTitle/XDSTopNavHeading, renames the XDSTopNavTitle component to XDSTopNavHeading, and updates import specifiers.',
+ pr: '#527',
+};
+
+const TITLE_PROP_COMPONENTS = new Set([
+ 'XDSTopNav',
+ 'XDSTopNavTitle',
+ 'XDSTopNavHeading',
+]);
+
+const IMPORT_RENAMES = {
+ XDSTopNavTitle: 'XDSTopNavHeading',
+ XDSTopNavTitleProps: 'XDSTopNavHeadingProps',
+};
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ // 1. Rename `title` prop to `heading` on target components
+ root.find(j.JSXOpeningElement).forEach((path) => {
+ const name = path.node.name;
+ if (name.type !== 'JSXIdentifier' || !TITLE_PROP_COMPONENTS.has(name.name)) {
+ return;
+ }
+
+ path.node.attributes.forEach((attr) => {
+ if (attr.type === 'JSXAttribute' && attr.name.name === 'title') {
+ attr.name.name = 'heading';
+ hasChanges = true;
+ }
+ });
+ });
+
+ // 2. Rename <XDSTopNavTitle> to <XDSTopNavHeading> (opening and closing tags)
+ root.find(j.JSXIdentifier, {name: 'XDSTopNavTitle'}).forEach((path) => {
+ path.node.name = 'XDSTopNavHeading';
+ hasChanges = true;
+ });
+
+ // 3. Rename import specifiers: XDSTopNavTitle → XDSTopNavHeading, XDSTopNavTitleProps → XDSTopNavHeadingProps
+ root.find(j.ImportSpecifier).forEach((path) => {
+ const imported = path.node.imported;
+ if (imported.type === 'Identifier' && imported.name in IMPORT_RENAMES) {
+ const oldName = imported.name;
+ const newName = IMPORT_RENAMES[oldName];
+ imported.name = newName;
+ // If the local name matches the old imported name, update it too
+ if (path.node.local && path.node.local.name === oldName) {
+ path.node.local.name = newName;
+ }
+ hasChanges = true;
+ }
+ });
+
+ return hasChanges ? root.toSource() : undefined;
+}
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index c71a33b047..709f1c4f7e 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -42,7 +42,7 @@ export const docs = {
topNav={<XDSTopNav heading={<XDSTopNavHeading heading="My App" />} />}
sideNav={
<XDSSideNav>
- <XDSSideNavSection heading="Main" isHeaderHidden>
+ <XDSSideNavSection title="Main" isHeaderHidden>
<XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
@@ -67,7 +67,7 @@ export const docs = {
}
topContent={<XDSButton label="Create new" variant="primary" />}
footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}>
- <XDSSideNavSection heading="Main">
+ <XDSSideNavSection title="Main">
<XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
@@ -83,7 +83,7 @@ export const docs = {
/>
</XDSSideNavSection>
- <XDSSideNavSection heading="Settings">
+ <XDSSideNavSection title="Settings">
<XDSSideNavItem label="General" href="/settings/general" />
<XDSSideNavItem label="Security" href="/settings/security" />
</XDSSideNavSection>
@@ -131,7 +131,7 @@ export const docs = {
code: `<XDSSideNav
header={<XDSSideNavHeading icon={<AppIcon />} heading="My App" headingHref="/" />}
topContent={<XDSButton label="Create new" variant="primary" />}>
- <XDSSideNavSection heading="Main">
+ <XDSSideNavSection title="Main">
<XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
<XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
</XDSSideNavSection>
@@ -335,21 +335,21 @@ export const docs = {
examples: [
{
label: 'Basic section',
- code: `<XDSSideNavSection heading="Main">
+ code: `<XDSSideNavSection title="Main">
<XDSSideNavItem label="Dashboard" href="/dashboard" />
<XDSSideNavItem label="Projects" href="/projects" />
</XDSSideNavSection>`,
},
{
label: 'With end content and hidden header',
- code: `<XDSSideNavSection heading="Settings" endContent={<XDSBadge>New</XDSBadge>}>
+ code: `<XDSSideNavSection title="Settings" endContent={<XDSBadge>New</XDSBadge>}>
<XDSSideNavItem label="General" href="/settings/general" />
<XDSSideNavItem label="Security" href="/settings/security" />
</XDSSideNavSection>`,
},
{
label: 'Hidden header (used with TopNav)',
- code: `<XDSSideNavSection heading="Main" isHeaderHidden>
+ code: `<XDSSideNavSection title="Main" isHeaderHidden>
<XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
</XDSSideNavSection>`,
},