feat: add @deprecated JSDoc comments to component library replacements#26696
Conversation
Added deprecation messages with README links to 20 component library files that have replacements in the MetaMask Design System (MMDS). Components updated: - Avatar components (AvatarAccount, AvatarBase, AvatarFavicon, AvatarGroup, AvatarIcon, AvatarNetwork, AvatarToken) - Badge components (BadgeBase, BadgeNetwork, BadgeNotifications, BadgeWrapper) - Button components (Button, ButtonIcon, ButtonLink, ButtonPrimary, ButtonSecondary) - Form components (Checkbox, TextField) - Other components (Card, Icon, Text) All deprecation messages follow the pattern: - @deprecated tag with clear migration guidance - Note that API may have changed - @see tag linking to MMDS component README This provides developers with clear migration paths and documentation links.
|
CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes. |
| /** | ||
| * @deprecated Please update your code to use `BadgeIcon` from `@metamask/design-system-react-native`. | ||
| * The API may have changed — compare props before migrating. | ||
| * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/BadgeIcon/README.md} | ||
| */ | ||
|
|
There was a problem hiding this comment.
Just double checking BadgeIcon is the correct replacement for BadgeNotification here @brianacnguyen? Storybook below
Takes an iconName 🤔
const BadgeNotifications = ({
style,
iconName,
testID,
}: BadgeNotificationsProps) => {
const { size: containerSize, onLayout: onLayoutContainerSize } =
useComponentSize();
const { styles } = useStyles(styleSheet, { style, containerSize });
return (
<BadgeBase
style={styles.base}
testID={testID}
onLayout={onLayoutContainerSize}
>
<Icon name={iconName} size={IconSize.Xss} color={IconColor.Inverse} />
</BadgeBase>
);
};
Moved deprecation JSDoc comments from file tops to immediately above their respective component definitions for better IDE integration and clarity. This placement allows developers to see deprecation warnings when they hover over or use the component, rather than only at file import time.
|
Updated all @deprecated comments to be placed just above their component definitions rather than at the top of the file. This ensures better IDE integration - developers will see the deprecation warning when they hover over or use the component, not just when importing the file. |
…tions Moved all deprecation JSDoc comments to be placed immediately above their component definitions for consistent IDE integration across all 20 components. Components updated: - Text, Icon, Checkbox - Button, ButtonIcon, ButtonPrimary, ButtonSecondary, ButtonLink - AvatarBase, AvatarIcon, AvatarNetwork, AvatarToken - BadgeBase, BadgeWrapper This ensures developers see deprecation warnings when using components, not just when importing files.
🔍 Smart E2E Test Selection
click to see 🤖 AI reasoning detailsE2E Test Selection:
No functional code changes were made to any component. The component implementations, props, styles, and behavior remain completely unchanged. These are purely cosmetic/documentation improvements that:
Since there are no functional changes, no E2E tests are needed to validate this PR. The changes cannot break any user flows or features. Performance Test Selection: |
| * The API may have changed — compare props before migrating. | ||
| * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/AvatarBase/README.md} | ||
| */ | ||
| const AvatarBase: React.FC<AvatarBaseProps> = ({ |
There was a problem hiding this comment.
The @deprecated tag is placed directly above the component const declaration rather than at the top of the file. This is intentional: TypeScript and IDE tooling only surface JSDoc annotations for the symbol they immediately precede, so file-level placement would have silently no-op'd on hover/autocomplete.
|
|
||
| /** | ||
| * @deprecated Please update your code to use `AvatarBase` from `@metamask/design-system-react-native`. | ||
| * The API may have changed — compare props before migrating. |
There was a problem hiding this comment.
The 'The API may have changed — compare props before migrating.' line is added to every component rather than just some. This is a blanket safety note since the design-system-react-native package evolved independently; consumers should not assume a direct prop-for-prop swap without checking the linked README.
| /** | ||
| * @deprecated Please update your code to use `BadgeCount`, `BadgeIcon`, `BadgeNetwork` or `BadgeStatus` from `@metamask/design-system-react-native`. | ||
| * The API may have changed — compare props before migrating. | ||
| * @see {@link https://github.com/MetaMask/metamask-design-system/tree/main/packages/design-system-react-native/src/components} |
There was a problem hiding this comment.
BadgeBase maps to four distinct components in the new package (BadgeCount, BadgeIcon, BadgeNetwork, BadgeStatus) rather than a single replacement, so the @see link points to the components directory instead of a specific README. Consumers need to identify the right replacement based on the badge type they are rendering.
| } from './ButtonLink.constants'; | ||
|
|
||
| /** | ||
| * @deprecated Please update your code to use `TextButton` from `@metamask/design-system-react-native`. |
There was a problem hiding this comment.
ButtonLink is renamed to TextButton in the design-system-react-native package, not just moved. Consumers migrating this component will need to update both the import path and the component name.
| import { DEFAULT_BUTTONPRIMARY_LABEL_TEXTVARIANT } from './ButtonPrimary.constants'; | ||
|
|
||
| /** | ||
| * @deprecated Please update your code to use `Button` from `@metamask/design-system-react-native` with variant `ButtonVariant.Primary`. |
There was a problem hiding this comment.
ButtonPrimary and ButtonSecondary are consolidated into a single Button component in the new package, selected via ButtonVariant.Primary and ButtonVariant.Secondary. This reflects a design-system API change where separate variant components are replaced with a single component plus a variant prop.
Description
This PR adds
@deprecatedJSDoc comments with README links to 20 component library files that have replacements in the MetaMask Design System (MMDS).The deprecation messages provide clear migration paths for developers by:
This work improves developer experience by making it easier to migrate from legacy component library components to the standardized MMDS components.
Changelog
CHANGELOG entry: null
Related issues
Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-494
Manual testing steps
Screenshots/Recordings
N/A - Documentation-only changes
Before
Components had either no deprecation messages or minimal ones without full context.
After
All 20 components now have consistent deprecation messages following this pattern:
Components updated:
Pre-merge author checklist
Pre-merge reviewer checklist
Note
Low Risk
Low risk documentation-only change: adds/standardizes
@deprecatedJSDoc blocks and external README links without altering component runtime behavior. Main risk is minor lint/formatting or tooling differences in how IDEs surface these comments.Overview
Adds consistent
@deprecatedJSDoc annotations across legacy component-library UI components (avatars, badges, buttons, checkbox, text field, icon, text), pointing developers to the equivalent@metamask/design-system-react-nativereplacements.Each deprecation notice now includes a migration caution about potential API differences and a direct link to the relevant MMDS README for the replacement component.
Written by Cursor Bugbot for commit 167e357. This will update automatically on new commits. Configure here.