[material-ui][Typography] Deprecate paragraph prop

[walston]

• I have followed (at least) the PR section of the contributing guide.

Resolves #42382, resolves #16926

[mui-bot]

Netlify deploy preview

• docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 50bb4a7

[aarongarciah]

Thanks @walston! I left a small comment. Apart from that, deprecating the paragraph prop in Typography requires some more work:

1. Deprecate the corresponding class name: .MuiTypography-paragraph. You can add a @⁠deprecated JSDoc tag to where it's defined: https://github.com/mui/material-ui/blob/next/packages/mui-material/src/Typography/typographyClasses.ts#L47-L48
2. Run pnpm proptypes && pnpm docs:api and commit the generated changes. These commands copy the corresponding code comments from .d.ts to .js files and update the corresponding .json files that the docs will read when building the docs website.
3. Document both deprecations (prop and class name) in the Migrating from deprecated APIs page (code). We can take inspiration from other deprecated props/class names documented on that very page. Remember to sort the newly added section alphabetically.
4. Remove all usages of paragraph within the codebase. The prop is being used in around 20 files. Maybe replacing paragraph with component="p" gutterBottom in some cases is fine, but the spacing will certainly change and this will cause some visual regression tests to fail. We'll need to check case by case.

Remember to read the contributing guidelines and feel free to ping me if you need help.

[walston]

thanks so much for the instructions @aarongarciah. Happy to make those changes later today.

[aarongarciah]

Hey @walston! Did you have a chance to take a look? We want to land this on v6, which should be out in the next few weeks.

[walston]

oh dang. I'd love that. Apologies, got caught up with a company onsite. I can spend some time working through these things next week. Top of my priorities list now!

[walston]

@aarongarciah As I update the migration doc, it looks like there's an expectation there will be a codemod to handle this... Am I expected to write that codemod?

[aarongarciah]

@walston in this case, I think a codemod doesn't make sense because there's no direct replacement for the paragraph behavior:

1. Renders as a <p> element.
2. Adds margin-bottom: 16px.

We could codemod number 1 with component="p", but we can't codemod number 2 because we can't possibly know what other styles are developers applying to the component instance and we might break their UIs. In this case, I think it makes sense to provide the instructions on how to migrate.

Even if it was possible, you could ask us to pick it up if you can't do it.

[arronhunt]

@aarongarciah I'm working with @walston to get this over the finish line :)

We could codemod number 1 with component="p", but we can't codemod number 2 because we can't possibly know what other styles are developers applying to the component instance and we might break their UIs. In this case, I think it makes sense to provide the instructions on how to migrate.

For 1: I don't think we event need to add the component prop, since <Typography> renders as a <p> by default. Unless a developer overrides this setting it would probably result in a lot of redundant code. Is there a way to check for this?

For 2: Would we want to suggest adding mb={2} for Typography elements that need margin? I'm still confused about MUI's preferences between mb and sx props for margins.

[aarongarciah]

Hey @arronhunt! Thanks for working on this.

From your comment I'm not sure if you're working on a codemod or not. Just in case, I think we shouldn't spend time in a codemod. Instead, we can focus on writing clear guidance on what changed in the Migrating from deprecated APIs page given we can't possibly know users' intent and where the styles are coming from.

---

For 1: I don't think we event need to add the component prop, since renders as a

by default. Unless a developer overrides this setting it would probably result in a lot of redundant code. Is there a way to check for this?

The tag being rendered by Typography depends on the variant and some other props. Typography renders a <p> in these scenarios:

• variant="body1" (body1 is also used when no variant is passed)
• variant="body2"
• paragraph
• component="p" or component={MyCustomComponent} (that renders a <p>)
• variant="any_variant" paragraph
• variant="any_variant" component="p"

It's fine to omit component="p" if no variant is passed or if the variant is already rendering a <p> (body1 and body2). See this demo for more info https://mui.com/material-ui/react-typography/#usage.

For 2: Would we want to suggest adding mb={2} for Typography elements that need margin? I'm still confused about MUI's preferences between mb and sx props for margins.

We'll remove system props (e.g. mb={2}) so it's recommended to use the sx prop. See this RFC and this in-progress PR if you want to know more.

[aarongarciah]

Hey @arronhunt @walston! Let me know if you need any help.

[arronhunt]

@aarongarciah I just pushed updates to the docs, using sx props to set bottom margin for paragraphs. I agree that a codemod isn't necessary and we can rely on the upgrade instructions. Would love your feedback!

[aarongarciah]

@DiegoAndai I just added a commit with the codemod. I went with 16px instead of 2 for the marginBottom value.

One doubt: should we cater for the mb shortcut being present in the object passed to sx?

[aarongarciah]

The idea is that if paragraph={false} (or other falsy value) we don't add any margin, we just remove the paragraph prop.

[aarongarciah]

I need to update the migration guide.

[aarongarciah]

Ready for review.