Skip to content

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

TypeScript

feat!: remove deprecated APIs and add icon migration codemod for v0.0.2 (#533)

Cindy Zhang7dfbef376d5a
diff --git a/packages/cli/src/codemods/transforms/v0.0.2/__tests__/migrate-useXDSIcon-to-getIcon.test.mjs b/packages/cli/src/codemods/transforms/v0.0.2/__tests__/migrate-useXDSIcon-to-getIcon.test.mjs
new file mode 100644
index 0000000000..f9039f9b94
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.2/__tests__/migrate-useXDSIcon-to-getIcon.test.mjs
@@ -0,0 +1,108 @@
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../migrate-useXDSIcon-to-getIcon.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('migrate-useXDSIcon-to-getIcon', () => {
+ it('renames useXDSIcon call to getIcon', async () => {
+ const input = `const icon = useXDSIcon('close');`;
+ const output = await applyTransform(input);
+ expect(output).toContain("getIcon('close')");
+ expect(output).not.toContain('useXDSIcon');
+ });
+
+ it('renames useXDSIcon in import specifiers', async () => {
+ const input = `import {useXDSIcon} from '@xds/core';
+const icon = useXDSIcon('close');`;
+ const output = await applyTransform(input);
+ expect(output).toMatch(/import\s*\{.*getIcon.*\}/);
+ expect(output).toContain("getIcon('close')");
+ expect(output).not.toContain('useXDSIcon');
+ });
+
+ it('updates import source from IconRegistry to globalIconRegistry', async () => {
+ const input = `import {useXDSIcon} from '../Icon/IconRegistry';
+const icon = useXDSIcon('close');`;
+ const output = await applyTransform(input);
+ expect(output).toMatch(/from\s+['"]\.\.\/Icon\/globalIconRegistry['"]/);
+ expect(output).toMatch(/import\s*\{.*getIcon.*\}/);
+ expect(output).not.toMatch(/['"]\.\.\/Icon\/IconRegistry['"]/);
+ expect(output).not.toContain('useXDSIcon');
+ });
+
+ it('removes IconRegistryContext from imports', async () => {
+ const input = `import {IconRegistryContext, useXDSIcon} from '@xds/core';
+const icon = useXDSIcon('close');`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('IconRegistryContext');
+ expect(output).toMatch(/import\s*\{.*getIcon.*\}/);
+ });
+
+ it('removes entire import when only IconRegistryContext', async () => {
+ const input = `import {IconRegistryContext} from '@xds/core';`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('import');
+ expect(output).not.toContain('IconRegistryContext');
+ });
+
+ it('removes IconRegistryContext.Provider wrapper', async () => {
+ const input = `<IconRegistryContext.Provider value={icons}>
+ <App />
+</IconRegistryContext.Provider>`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('IconRegistryContext');
+ expect(output).not.toContain('Provider');
+ expect(output).toContain('<App />');
+ });
+
+ it('preserves @xds/core import source', async () => {
+ const input = `import {useXDSIcon} from '@xds/core';
+const icon = useXDSIcon('close');`;
+ const output = await applyTransform(input);
+ expect(output).toContain("from '@xds/core'");
+ expect(output).toMatch(/import\s*\{.*getIcon.*\}/);
+ });
+
+ it('handles aliased import', async () => {
+ const input = `import {useXDSIcon as getMyIcon} from '@xds/core';
+const icon = getMyIcon('close');`;
+ const output = await applyTransform(input);
+ expect(output).toContain('getIcon as getMyIcon');
+ });
+
+ it('returns undefined when no changes needed', async () => {
+ const {default: transform} = await import(
+ '../migrate-useXDSIcon-to-getIcon.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const source = `const icon = getIcon('close');`;
+ const result = transform({source, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+
+ it('handles multiple useXDSIcon calls in one file', async () => {
+ const input = `import {useXDSIcon} from '@xds/core';
+const close = useXDSIcon('close');
+const check = useXDSIcon('check');`;
+ const output = await applyTransform(input);
+ expect(output).toContain("getIcon('close')");
+ expect(output).toContain("getIcon('check')");
+ expect(output).not.toContain('useXDSIcon');
+ });
+
+ it('updates relative IconRegistry import path', async () => {
+ const input = `import {useXDSIcon} from './IconRegistry';
+const icon = useXDSIcon('close');`;
+ const output = await applyTransform(input);
+ expect(output).toMatch(/from\s*['"]\.\/globalIconRegistry['"]/);
+ });
+});
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 59699e0697..597716e439 100644
--- a/packages/cli/src/codemods/transforms/v0.0.2/index.mjs
+++ b/packages/cli/src/codemods/transforms/v0.0.2/index.mjs
@@ -28,6 +28,9 @@ import renameTopNavTitleToHeading, {
import renameSideNavHeaderToHeading, {
meta as sideNavHeaderMeta,
} from './rename-sidenav-header-to-heading.mjs';
+import migrateUseXDSIconToGetIcon, {
+ meta as useXDSIconMeta,
+} from './migrate-useXDSIcon-to-getIcon.mjs';
export default [
{
name: 'rename-selector-items-to-options',
@@ -69,4 +72,9 @@ export default [
transform: renameSideNavHeaderToHeading,
meta: sideNavHeaderMeta,
},
+ {
+ name: 'migrate-useXDSIcon-to-getIcon',
+ transform: migrateUseXDSIconToGetIcon,
+ meta: useXDSIconMeta,
+ },
];
diff --git a/packages/cli/src/codemods/transforms/v0.0.2/migrate-useXDSIcon-to-getIcon.mjs b/packages/cli/src/codemods/transforms/v0.0.2/migrate-useXDSIcon-to-getIcon.mjs
new file mode 100644
index 0000000000..87ba2bdf55
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.2/migrate-useXDSIcon-to-getIcon.mjs
@@ -0,0 +1,120 @@
+/**
+ * @file Codemod: Migrate useXDSIcon → getIcon, remove IconRegistryContext
+ * @see https://github.com/facebookexperimental/xds/pull/531
+ *
+ * - Renames useXDSIcon(...) calls to getIcon(...)
+ * - Updates import specifiers: useXDSIcon → getIcon
+ * - Updates import source from IconRegistry to globalIconRegistry (internal imports)
+ * - Removes IconRegistryContext from imports (removes entire import if nothing left)
+ * - Removes IconRegistryContext.Provider JSX wrappers (replaces with children)
+ */
+
+export const meta = {
+ title: 'Migrate useXDSIcon → getIcon, remove IconRegistryContext',
+ description:
+ 'Renames useXDSIcon() to getIcon(), updates import sources from IconRegistry to globalIconRegistry, and removes IconRegistryContext usage.',
+ pr: '#531',
+};
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ // 1. Rename useXDSIcon → getIcon in call expressions
+ root
+ .find(j.CallExpression, {
+ callee: {type: 'Identifier', name: 'useXDSIcon'},
+ })
+ .forEach((path) => {
+ path.node.callee.name = 'getIcon';
+ hasChanges = true;
+ });
+
+ // 2. Update import specifiers: useXDSIcon → getIcon
+ root.find(j.ImportSpecifier).forEach((path) => {
+ const imported = path.node.imported;
+ if (imported.type === 'Identifier' && imported.name === 'useXDSIcon') {
+ const oldLocal = path.node.local ? path.node.local.name : null;
+ imported.name = 'getIcon';
+ // If local name matched old imported name, update it too
+ if (oldLocal === 'useXDSIcon') {
+ path.node.local.name = 'getIcon';
+ }
+ hasChanges = true;
+ }
+ });
+
+ // 3. Remove IconRegistryContext from import specifiers
+ root.find(j.ImportDeclaration).forEach((path) => {
+ const specifiers = path.node.specifiers;
+ if (!specifiers) return;
+
+ const filtered = specifiers.filter((s) => {
+ if (
+ s.type === 'ImportSpecifier' &&
+ s.imported.type === 'Identifier' &&
+ s.imported.name === 'IconRegistryContext'
+ ) {
+ hasChanges = true;
+ return false;
+ }
+ return true;
+ });
+
+ if (filtered.length === 0) {
+ // All specifiers removed — remove the entire import
+ j(path).remove();
+ } else if (filtered.length !== specifiers.length) {
+ path.node.specifiers = filtered;
+ }
+ });
+
+ // 4. Update import source: '../Icon/IconRegistry' or similar → '../Icon/globalIconRegistry'
+ root.find(j.ImportDeclaration).forEach((path) => {
+ const source = path.node.source.value;
+ if (typeof source === 'string' && source.includes('IconRegistry') && !source.includes('globalIconRegistry')) {
+ path.node.source.value = source.replace(
+ /IconRegistry$/,
+ 'globalIconRegistry',
+ );
+ hasChanges = true;
+ }
+ });
+
+ // 5. Remove <IconRegistryContext.Provider> wrappers — replace with children
+ root.find(j.JSXElement).forEach((path) => {
+ const opening = path.node.openingElement;
+ if (
+ opening.name.type === 'JSXMemberExpression' &&
+ opening.name.object.type === 'JSXIdentifier' &&
+ opening.name.object.name === 'IconRegistryContext' &&
+ opening.name.property.type === 'JSXIdentifier' &&
+ opening.name.property.name === 'Provider'
+ ) {
+ // Replace the Provider element with its children
+ const children = path.node.children;
+ if (children.length === 1) {
+ j(path).replaceWith(children[0]);
+ } else {
+ // Wrap multiple children in a fragment
+ j(path).replaceWith(
+ j.jsxFragment(j.jsxOpeningFragment(), j.jsxClosingFragment(), children),
+ );
+ }
+ hasChanges = true;
+ }
+ });
+
+ // 6. Remove identifiers referencing IconRegistryContext (variable declarations, etc.)
+ root
+ .find(j.VariableDeclarator, {
+ init: {type: 'Identifier', name: 'IconRegistryContext'},
+ })
+ .forEach((path) => {
+ j(path.parent).remove();
+ hasChanges = true;
+ });
+
+ return hasChanges ? root.toSource() : undefined;
+}
diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsx
deleted file mode 100644
index e2b8cc57ed..0000000000
--- a/packages/core/src/Icon/IconRegistry.tsx
+++ /dev/null
@@ -1,82 +0,0 @@
-/**
- * @file IconRegistry.tsx
- * @input Uses React createContext, useContext
- * @output Exports IconRegistryContext, useXDSIcon hook (both deprecated)
- * @position Legacy client-side icon context. Kept for backward compatibility.
- *
- * @deprecated All icon resolution now uses getIcon() from globalIconRegistry.tsx.
- * Components should import { getIcon } from './globalIconRegistry' instead.
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Icon/globalIconRegistry.tsx (global registry, types)
- * - /packages/core/src/Icon/Icon.doc.mjs (features, usage)
- * - /packages/core/src/Icon/index.ts (exports)
- */
-
-'use client';
-
-import {createContext, useContext, type ReactNode} from 'react';
-import {defaultIcons} from './defaultIcons';
-import type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';
-import {getGlobalRegistry} from './globalIconRegistry';
-
-// Re-export types so existing imports from this file still work
-export type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';
-
-// =============================================================================
-// Context
-// =============================================================================
-
-/**
- * Context for providing theme icons to components.
- * Accepts a full or partial registry. When null, components fall back
- * to the global registry, then to built-in lightweight SVGs.
- *
- * @deprecated Icons are now global via registerIcons(). Context is no longer needed.
- * Use registerIcons() from globalIconRegistry to set icons, and getIcon() to retrieve them.
- */
-export const IconRegistryContext =
- createContext<Partial<XDSIconRegistry> | null>(null);
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Hook to retrieve an icon by semantic name (client components only).
- *
- * Resolution order:
- * 1. Context registry (via XDSTheme's IconRegistryContext)
- * 2. Global registry (via registerIcons())
- * 3. Built-in lightweight SVG fallback
- *
- * @deprecated Use getIcon() from globalIconRegistry instead for RSC compatibility.
- * getIcon() works in both server and client environments without React Context.
- *
- * @example
- * ```
- * // Before (deprecated):
- * const closeIcon = useXDSIcon('close');
- *
- * // After (preferred):
- * import { getIcon } from '@xds/core';
- * const closeIcon = getIcon('close');
- * ```
- */
-export function useXDSIcon(name: XDSIconName): ReactNode {
- const contextRegistry = useContext(IconRegistryContext);
- const globalRegistry = getGlobalRegistry();
-
- // Context wins (tree-scoped theme override)
- if (contextRegistry != null && contextRegistry[name] != null) {
- return contextRegistry[name];
- }
-
- // Global registry (module-level, works server-side too)
- if (globalRegistry[name] != null) {
- return globalRegistry[name];
- }
-
- // Built-in fallback
- return defaultIcons[name];
-}
diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsx
index 07aa267bd9..3b8c64972a 100644
--- a/packages/core/src/Icon/defaultIcons.tsx
+++ b/packages/core/src/Icon/defaultIcons.tsx
@@ -17,11 +17,11 @@
* - Status icons (checkCircle, xCircle, warning) use solid fills for better color visibility
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Icon/IconRegistry.tsx (XDSIconName type if names change)
+ * - /packages/core/src/Icon/globalIconRegistry.tsx (XDSIconName type if names change)
* - /packages/core/src/Icon/Icon.doc.mjs (fallback icon documentation)
*/
-import type {XDSIconRegistry} from './IconRegistry';
+import type {XDSIconRegistry} from './globalIconRegistry';
const svgProps = {
xmlns: 'http://www.w3.org/2000/svg',
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
index 987474f48c..7d0ddabe91 100644
--- a/packages/core/src/Icon/globalIconRegistry.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -79,15 +79,6 @@ export function getIcon(name: XDSIconName): ReactNode {
return globalRegistry[name] ?? defaultIcons[name];
}
-/**
- * Get the raw global registry (internal use).
- * @internal
- * @deprecated Internal use only — will be removed when useXDSIcon is removed.
- */
-export function getGlobalRegistry(): Partial<XDSIconRegistry> {
- return globalRegistry;
-}
-
/**
* Reset the global registry. For testing only.
* @internal
diff --git a/packages/core/src/Icon/index.ts b/packages/core/src/Icon/index.ts
index 30faddcb5d..f55b9662e0 100644
--- a/packages/core/src/Icon/index.ts
+++ b/packages/core/src/Icon/index.ts
@@ -18,7 +18,3 @@ export type {
// Global registry (RSC-compatible, no 'use client')
export {registerIcons, getIcon, resetIcons} from './globalIconRegistry';
export type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';
-
-// Context registry (client-only, deprecated)
-/** @deprecated Use registerIcons() and getIcon() from globalIconRegistry instead. */
-export {IconRegistryContext, useXDSIcon} from './IconRegistry';
diff --git a/packages/core/src/SideNav/index.ts b/packages/core/src/SideNav/index.ts
index 69fe708b4f..70b706fb1d 100644
--- a/packages/core/src/SideNav/index.ts
+++ b/packages/core/src/SideNav/index.ts
@@ -13,11 +13,6 @@ export type {XDSSideNavProps} from './XDSSideNav';
export {XDSSideNavHeading} from './XDSSideNavHeading';
export type {XDSSideNavHeadingProps} from './XDSSideNavHeading';
-/** @deprecated Use XDSSideNavHeading instead */
-export {XDSSideNavHeading as XDSSideNavHeader} from './XDSSideNavHeading';
-/** @deprecated Use XDSSideNavHeadingProps instead */
-export type {XDSSideNavHeadingProps as XDSSideNavHeaderProps} from './XDSSideNavHeading';
-
export {XDSSideNavItem} from './XDSSideNavItem';
export type {XDSSideNavItemProps} from './XDSSideNavItem';
diff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.ts
index 38a03fa333..97e2901404 100644
--- a/packages/core/src/TopNav/index.ts
+++ b/packages/core/src/TopNav/index.ts
@@ -13,11 +13,6 @@ export type {XDSTopNavProps} from './XDSTopNav';
export {XDSTopNavHeading} from './XDSTopNavHeading';
export type {XDSTopNavHeadingProps} from './XDSTopNavHeading';
-/** @deprecated Use XDSTopNavHeading instead */
-export {XDSTopNavHeading as XDSTopNavTitle} from './XDSTopNavHeading';
-/** @deprecated Use XDSTopNavHeadingProps instead */
-export type {XDSTopNavHeadingProps as XDSTopNavTitleProps} from './XDSTopNavHeading';
-
export {XDSTopNavItem} from './XDSTopNavItem';
export type {XDSTopNavItemProps} from './XDSTopNavItem';
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index f58bf99b53..5c3513e636 100644
--- a/packages/core/src/theme/defineTheme.ts
+++ b/packages/core/src/theme/defineTheme.ts
@@ -28,7 +28,7 @@
* ```
*/
-import type {XDSIconRegistry} from '../Icon/IconRegistry';
+import type {XDSIconRegistry} from '../Icon/globalIconRegistry';
import {parseStyleKey} from '../utils/parseStyleKey';
import {
colorDefaults,