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.mjsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.tsxdeleted file mode 100644index 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.tsxindex 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.tsxindex 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.* @internaldiff --git a/packages/core/src/Icon/index.ts b/packages/core/src/Icon/index.tsindex 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.tsindex 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.tsindex 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.tsindex 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,