[material-ui][Backdrop] Deprecate components and componentsProps (#…

…42468)
mui · Jun 3, 2024 · cdde927 · cdde927
1 parent 95099c3
commit cdde927
Show file tree

Hide file tree

Showing 12 changed files with 193 additions and 62 deletions.
diff --git a/...rial/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md b/...rial/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md
@@ -379,6 +379,28 @@ Use the [codemod](https://github.com/mui/material-ui/tree/HEAD/packages/mui-code
 npx @mui/codemod@next deprecations/backdrop-props <path>
 ```
 
+### components
+
+The Backdrop's `components` prop was deprecated in favor of `slots`:
+
+```diff
+ <Backdrop
+-  components={{ root: CustomRoot }}
++  slots={{ root: CustomRoot }}
+ />
+```
+
+### componentsProps
+
+The Backdrop's `componentsProps` prop was deprecated in favor of `slotProps`:
+
+```diff
+ <Backdrop
+-  componentsProps={{ root: { testid: 'test-id' } }}
++  slotProps={{ root: { testid: 'test-id' } }}
+ />
+```
+
 ### TransitionComponent
 
 The Backdrop's `TransitionComponent` prop was deprecated in favor of `slots.transition`:

diff --git a/docs/pages/material-ui/api/backdrop.json b/docs/pages/material-ui/api/backdrop.json
@@ -6,11 +6,15 @@
     "component": { "type": { "name": "elementType" } },
     "components": {
       "type": { "name": "shape", "description": "{ Root?: elementType }" },
-      "default": "{}"
+      "default": "{}",
+      "deprecated": true,
+      "deprecationInfo": "Use the <code>slots</code> prop instead. This prop will be removed in v7. See <a href=\"/material-ui/migration/migrating-from-deprecated-apis/\">Migrating from deprecated APIs</a> for more details."
     },
     "componentsProps": {
       "type": { "name": "shape", "description": "{ root?: object }" },
-      "default": "{}"
+      "default": "{}",
+      "deprecated": true,
+      "deprecationInfo": "Use the <code>slotProps</code> prop instead. This prop will be removed in v7. See <a href=\"/material-ui/migration/migrating-from-deprecated-apis/\">Migrating from deprecated APIs</a> for more details."
     },
     "invisible": { "type": { "name": "bool" }, "default": "false" },
     "slotProps": {

diff --git a/docs/translations/api-docs/backdrop/backdrop.json b/docs/translations/api-docs/backdrop/backdrop.json
@@ -6,11 +6,9 @@
     "component": {
       "description": "The component used for the root node. Either a string to use a HTML element or a component."
     },
-    "components": {
-      "description": "The components used for each slot inside.<br>This prop is an alias for the <code>slots</code> prop. It&#39;s recommended to use the <code>slots</code> prop instead."
-    },
+    "components": { "description": "The components used for each slot inside." },
     "componentsProps": {
-      "description": "The extra props for the slot components. You can override the existing props or add new ones.<br>This prop is an alias for the <code>slotProps</code> prop. It&#39;s recommended to use the <code>slotProps</code> prop instead, as <code>componentsProps</code> will be deprecated in the future."
+      "description": "The extra props for the slot components. You can override the existing props or add new ones."
     },
     "invisible": {
       "description": "If <code>true</code>, the backdrop is invisible. It can be used when rendering a popover or a custom select component."

diff --git a/packages/mui-codemod/README.md b/packages/mui-codemod/README.md
@@ -391,6 +391,26 @@ npx @mui/codemod@next deprecations/avatar-group-props <path>
 
 #### `backdrop-props`
 
+```diff
+ <Backdrop
+-  components={{ Root: CustomRoot }}
++  slots={{ root: CustomRoot }}
+-  componentsProps={{ root: { testid: 'test-id' } }}
++  slotProps={{ root: { testid: 'test-id' } }}
+ />
+```
+
+```diff
+ MuiBackdrop: {
+   defaultProps: {
+-    components: { Root: CustomRoot }
++    slots: { root: CustomRoot },
+-    componentsProps: { root: { testid: 'root-id' } }
++    slotProps: { root: { testid: 'root-id' } },
+  },
+ },
+```
+
 ```diff
  <Backdrop
 -    TransitionComponent={CustomTransition}

diff --git a/packages/mui-codemod/src/deprecations/backdrop-props/backdrop-props.js b/packages/mui-codemod/src/deprecations/backdrop-props/backdrop-props.js
@@ -1,4 +1,5 @@
 import movePropIntoSlots from '../utils/movePropIntoSlots';
+import replaceComponentsWithSlots from '../utils/replaceComponentsWithSlots';
 
 /**
  * @param {import('jscodeshift').FileInfo} file
@@ -9,6 +10,8 @@ export default function transformer(file, api, options) {
   const root = j(file.source);
   const printOptions = options.printOptions;
 
+  replaceComponentsWithSlots(j, { root, componentName: 'Backdrop' });
+
   movePropIntoSlots(j, {
     root,
     componentName: 'Backdrop',

diff --git a/packages/mui-codemod/src/deprecations/backdrop-props/backdrop-props.test.js b/packages/mui-codemod/src/deprecations/backdrop-props/backdrop-props.test.js
@@ -1,53 +1,16 @@
-import path from 'path';
-import { expect } from 'chai';
-import { jscodeshift } from '../../../testUtils';
+import { describeJscodeshiftTransform } from '../../../testUtils';
 import transform from './backdrop-props';
-import readFile from '../../util/readFile';
-
-function read(fileName) {
-  return readFile(path.join(__dirname, fileName));
-}
 
 describe('@mui/codemod', () => {
   describe('deprecations', () => {
-    describe('backdrop-props', () => {
-      it('transforms props as needed', () => {
-        const actual = transform({ source: read('./test-cases/actual.js') }, { jscodeshift }, {});
-
-        const expected = read('./test-cases/expected.js');
-        expect(actual).to.equal(expected, 'The transformed version should be correct');
-      });
-
-      it('should be idempotent', () => {
-        const actual = transform({ source: read('./test-cases/expected.js') }, { jscodeshift }, {});
-
-        const expected = read('./test-cases/expected.js');
-        expect(actual).to.equal(expected, 'The transformed version should be correct');
-      });
-    });
-
-    describe('[theme] backdrop-props', () => {
-      it('transforms props as needed', () => {
-        const actual = transform(
-          { source: read('./test-cases/theme.actual.js') },
-          { jscodeshift },
-          {},
-        );
-
-        const expected = read('./test-cases/theme.expected.js');
-        expect(actual).to.equal(expected, 'The transformed version should be correct');
-      });
-
-      it('should be idempotent', () => {
-        const actual = transform(
-          { source: read('./test-cases/theme.expected.js') },
-          { jscodeshift },
-          {},
-        );
-
-        const expected = read('./test-cases/theme.expected.js');
-        expect(actual).to.equal(expected, 'The transformed version should be correct');
-      });
+    describeJscodeshiftTransform({
+      transform,
+      transformName: 'backdrop-props',
+      dirname: __dirname,
+      testCases: [
+        { actual: '/test-cases/actual.js', expected: '/test-cases/expected.js' },
+        { actual: '/test-cases/theme.actual.js', expected: '/test-cases/theme.expected.js' },
+      ],
     });
   });
 });
diff --git a/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/actual.js b/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/actual.js
@@ -19,8 +19,22 @@ import { Backdrop as MyBackdrop } from '@mui/material';
   TransitionComponent={ComponentTransition}
   slots={{
     root: 'div',
-    transition: SlotTransition
+    transition: SlotTransition,
   }}
 />;
+
 // should skip non MUI components
 <NonMuiBackdrop TransitionComponent={CustomTransition} />;
+
+<Backdrop components={{ Root: ComponentsRoot }} componentsProps={{ root: componentsRootProps }} />;
+<MyBackdrop components={{ Root: ComponentsRoot }} slotProps={{ root: slotsRootProps }} />;
+<Backdrop slots={{ root: SlotsRoot }} componentsProps={{ root: componentsRootProps }} />;
+<MyBackdrop
+  slots={{ root: SlotsRoot }}
+  components={{ Root: ComponentsRoot }}
+  slotProps={{ root: slotsRootProps }}
+  componentsProps={{ root: componentsRootProps }}
+/>;
+
+// should skip non MUI components
+<NonMuiBackdrop components={{ Root: ComponentsRoot }} />;
diff --git a/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/expected.js b/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/expected.js
@@ -20,7 +20,25 @@ import { Backdrop as MyBackdrop } from '@mui/material';
 <Backdrop
   slots={{
     root: 'div',
-    transition: SlotTransition
+    transition: SlotTransition,
   }} />;
+
 // should skip non MUI components
 <NonMuiBackdrop TransitionComponent={CustomTransition} />;
+
+<Backdrop slots={{
+  root: ComponentsRoot
+}} slotProps={{ root: componentsRootProps }} />;
+<MyBackdrop slotProps={{ root: slotsRootProps }} slots={{
+  root: ComponentsRoot
+}} />;
+<Backdrop slots={{ root: SlotsRoot }} slotProps={{ root: componentsRootProps }} />;
+<MyBackdrop
+  slots={{ root: SlotsRoot }}
+  slotProps={{ root: {
+    ...componentsRootProps,
+    ...slotsRootProps
+  } }} />;
+
+// should skip non MUI components
+<NonMuiBackdrop components={{ Root: ComponentsRoot }} />;
diff --git a/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/theme.actual.js b/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/theme.actual.js
@@ -28,3 +28,41 @@ fn({
     },
   },
 });
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      components: { Root: ComponentsRoot },
+      componentsProps: { root: componentsRootProps },
+    },
+  },
+});
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      components: { Root: ComponentsRoot },
+      slotProps: { root: slotsRootProps },
+    },
+  },
+});
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      slots: { root: SlotsRoot },
+      componentsProps: { root: componentsRootProps },
+    },
+  },
+});
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      slots: { root: SlotsRoot },
+      components: { Root: ComponentsRoot },
+      slotProps: { root: slotsRootProps },
+      componentsProps: { root: componentsRootProps },
+    },
+  },
+});
diff --git a/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/theme.expected.js b/packages/mui-codemod/src/deprecations/backdrop-props/test-cases/theme.expected.js
@@ -29,3 +29,58 @@ fn({
     },
   },
 });
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      slots: {
+        root: ComponentsRoot
+      },
+
+      slotProps: {
+        root: componentsRootProps
+      }
+    },
+  },
+});
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      slotProps: { root: slotsRootProps },
+
+      slots: {
+        root: ComponentsRoot
+      }
+    },
+  },
+});
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      slots: { root: SlotsRoot },
+
+      slotProps: {
+        root: componentsRootProps
+      }
+    },
+  },
+});
+
+fn({
+  MuiBackdrop: {
+    defaultProps: {
+      slots: {
+        root: SlotsRoot
+      },
+
+      slotProps: {
+        root: {
+          ...componentsRootProps,
+          ...slotsRootProps
+        }
+      }
+    },
+  },
+});
diff --git a/packages/mui-material/src/Backdrop/Backdrop.d.ts b/packages/mui-material/src/Backdrop/Backdrop.d.ts
@@ -52,8 +52,7 @@ export interface BackdropOwnProps
   /**
    * The components used for each slot inside.
    *
-   * This prop is an alias for the `slots` prop.
-   * It's recommended to use the `slots` prop instead.
+   * @deprecated Use the `slots` prop instead. This prop will be removed in v7. See [Migrating from deprecated APIs](/material-ui/migration/migrating-from-deprecated-apis/) for more details.
    *
    * @default {}
    */
@@ -64,8 +63,7 @@ export interface BackdropOwnProps
    * The extra props for the slot components.
    * You can override the existing props or add new ones.
    *
-   * This prop is an alias for the `slotProps` prop.
-   * It's recommended to use the `slotProps` prop instead, as `componentsProps` will be deprecated in the future.
+   * @deprecated Use the `slotProps` prop instead. This prop will be removed in v7. See [Migrating from deprecated APIs](/material-ui/migration/migrating-from-deprecated-apis/) for more details.
    *
    * @default {}
    */

diff --git a/packages/mui-material/src/Backdrop/Backdrop.js b/packages/mui-material/src/Backdrop/Backdrop.js
@@ -134,8 +134,7 @@ Backdrop.propTypes /* remove-proptypes */ = {
   /**
    * The components used for each slot inside.
    *
-   * This prop is an alias for the `slots` prop.
-   * It's recommended to use the `slots` prop instead.
+   * @deprecated Use the `slots` prop instead. This prop will be removed in v7. See [Migrating from deprecated APIs](/material-ui/migration/migrating-from-deprecated-apis/) for more details.
    *
    * @default {}
    */
@@ -146,8 +145,7 @@ Backdrop.propTypes /* remove-proptypes */ = {
    * The extra props for the slot components.
    * You can override the existing props or add new ones.
    *
-   * This prop is an alias for the `slotProps` prop.
-   * It's recommended to use the `slotProps` prop instead, as `componentsProps` will be deprecated in the future.
+   * @deprecated Use the `slotProps` prop instead. This prop will be removed in v7. See [Migrating from deprecated APIs](/material-ui/migration/migrating-from-deprecated-apis/) for more details.
    *
    * @default {}
    */