[docs] Allow function prop to return undefined

[m4theushw]

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

If a prop receives a function whose return has undefined, then yarn docs:api crashes with:

TypeError: resolveType for 'UndefinedLiteral' not implemented

This can be tested applying the diff below:

diff --git a/packages/mui-material/src/Rating/Rating.d.ts b/packages/mui-material/src/Rating/Rating.d.ts
index 1eb262d4c4..704c4443f9 100644
--- a/packages/mui-material/src/Rating/Rating.d.ts
+++ b/packages/mui-material/src/Rating/Rating.d.ts
@@ -42,12 +42,12 @@ export interface RatingProps
    *
    * For localization purposes, you can use the provided [translations](/material-ui/guides/localization/).
    * @param {number} value The rating label's value to format.
-   * @returns {string}
+   * @returns {string | undefined}
    * @default function defaultLabelText(value) {
    *   return `${value} Star${value !== 1 ? 's' : ''}`;
    * }
    */
-  getLabelText?: (value: number) => string;
+  getLabelText?: (value: number) => string | undefined;
   /**
    * If `true`, only the selected icon will be highlighted.
    * @default false

The reason for this change is because in mui/mui-x#4859 I added a prop to the DataGrid which can return null and other values. I can't add undefined because the docs generator crashes.

[mui-bot]

No bundle size changes

Generated by 🚫 dangerJS against 93dbf9d

[siriwatknp]

@m4theushw is it better to use React.ReactNode?

[m4theushw]

@siriwatknp I didn't understand you. Do you mean to use React.ReactNode in the diff? The diff is only an example of how to test this PR. In mui/mui-x#4859 I don't want to support React elements.

[siriwatknp]

@m4theushw I mean we can just update the getLabelText type to return React.ReactNode instead of string and run docs:api. It looks better from the Material UI perspective. Does it work for mui-x?

diff --git a/packages/mui-material/src/Rating/Rating.d.ts b/packages/mui-material/src/Rating/Rating.d.ts
index 1eb262d4c4..667ee0aaeb 100644
--- a/packages/mui-material/src/Rating/Rating.d.ts
+++ b/packages/mui-material/src/Rating/Rating.d.ts
@@ -47,7 +47,7 @@ export interface RatingProps
    *   return `${value} Star${value !== 1 ? 's' : ''}`;
    * }
    */
-  getLabelText?: (value: number) => string;
+  getLabelText?: (value: number) => React.ReactNode;
   /**
    * If `true`, only the selected icon will be highlighted.
    * @default false

[m4theushw]

@siriwatknp Replacing string with React.ReactNode could work, but I don't want to change the Rating component. I only used getLabelText because it was the first function prop I found to demonstrate the bug. In MUI X I don't want to use React.ReactNode.

[siriwatknp]

👍 Looks good.

[oliviertassinari]

For context, getLabelText is applied as a DOM attribute, it has to be a string.

material-ui/packages/mui-material/src/Rating/Rating.js

Line 505 in 4ab3a04

aria-label={readOnly ? getLabelText(value) : null}

I also suspect that it should never be an empty string/null/undefined.

---

The reason for this change is because in mui/mui-x#4859 I added a prop to the DataGrid which can return null and other values. I can't add undefined because the docs generator crashes.

@m4theushw It could have been great to have an exact example on this PR. It's not clear to me why we need to support undefined.

[m4theushw]

@oliviertassinari This PR was created to allow getRowHeight prop to receive () => undefined or () => null. Since we don't change the behavior based on the return, for better DX we support all. If only () => null is supported, developers will have to figure out why the other value can't be used.

The prop is in https://github.com/mui/mui-x/blob/9e317d512d0f1f637961003b9f5de9a40eb54b3b/packages/grid/x-data-grid/src/models/params/gridRowParams.ts#L66

[oliviertassinari]

@m4theushw Thanks for the context:

I see this approach used here as well:

We might be able to argue that using only one of the two for the types and the docs could improve the DX too. Why? Because it would mean that developers don't have to choose between using null or undefined, we made the decision for them. We could make the code support any nullish value to avoid breaking changes (but without encouraging it). So in the end, maybe:

export type GridRowHeightReturnValue = number | undefined | 'auto';

is a step forward. But then, it's a bit confusing for me. What does returning undefined mean? I had to check the docs to understand. So maybe this would be even clearer 🤷‍♂️:

export type GridRowHeightReturnValue = number | 'props.rowHeight' | 'auto';