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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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><XDSSideNavItemlabel="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"><XDSSideNavItemlabel="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: `<XDSSideNavheader={<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>`,},