Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs] Add ref forwarding to API docs #15135

Merged
merged 6 commits into from Apr 4, 2019
Merged

[docs] Add ref forwarding to API docs #15135

merged 6 commits into from Apr 4, 2019

Conversation

eps1lon
Copy link
Member

@eps1lon eps1lon commented Mar 31, 2019 •
edited

Adds explicit documentation to https://material-ui.com/api/* about ref forwarding. Requires #15131 to not report false positives.

Finishes one point in #14415.

@eps1lon eps1lon added the docs Improvements or additions to the documentation label Mar 31, 2019
@eps1lon eps1lon added this to the v4 milestone Mar 31, 2019
@mui-pr-bot
Copy link

mui-pr-bot commented Mar 31, 2019 •
edited

No bundle size changes comparing ae24eea...27fd460

Generated by 🚫 dangerJS against 27fd460

oliviertassinari
oliviertassinari reviewed Mar 31, 2019
View reviewed changes
Copy link
Member

@oliviertassinari oliviertassinari left a comment •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the ref always be forwarded to the root element?
What about writing it down on all the documentation pages? This way, we will get bug issue reports on the components that don't follow it. Issue reports we can fix.

pages/api/backdrop.md Outdated Show resolved Hide resolved
pages/api/container.md Outdated Show resolved Hide resolved
eps1lon
eps1lon commented Apr 1, 2019
View reviewed changes
docs/src/modules/utils/generateMarkdown.js Outdated
@@ -273,6 +273,10 @@ function generateProps(reactAPI) {
return textProps;
}, text);

text = `${text}\nThe \`ref\` is ${
reactAPI.forwardsRefTo == null ? '**not** ' : ''
}forwarded to the root element.\n`;
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We probably need more granular control of this. I'm not sure this is always the "root element" (in any definition proposed in #15138).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have one case where it's not the case <ListItem button />. We might have another one with InputBase.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ListItem is actually a component where I would consider the current behavior a bug. But it's a component that is good example where "root = outermost" definition breaks.

InputBase looks good to me.

We can improve the test for this behavior with one of your suggestions from #15138 (comment)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

InputBase looks good to me.

I mean, if we move #14580 forward.

eps1lon
eps1lon commented Apr 3, 2019
View reviewed changes
docs/src/modules/utils/generateMarkdown.js
@@ -273,6 +273,14 @@ function generateProps(reactAPI) {
return textProps;
}, text);

let refHint = 'The `ref` is forwarded to the root element.';
if (reactAPI.forwardsRefTo == null) {
refHint = 'The component cannot hold a ref.';
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the case for almost all components that do not forward refs. Even if some of them can hold a ref we want to prevent users from doing that because converting those components to function components would be breaking.

docs/src/modules/utils/generateMarkdown.js
if (reactAPI.forwardsRefTo == null) {
refHint = 'The component cannot hold a ref.';
} else if (reactAPI.forwardsRefTo === 'React.Component') {
refHint = 'The `ref` is attached to a component class.';
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TouchRipple is the only candidate for that (allows imperative handle). The other components will be covered by #15170.

@eps1lon eps1lon marked this pull request as ready for review April 3, 2019 12:53
@eps1lon
Copy link
Member Author

eps1lon commented Apr 3, 2019

What about writing it down on all the documentation pages?

This should be addressed now. Every API page has a hint about ref forwarding. There are currently 3 different hints:

The ref is forwarded to the root element.

The component cannot hold a ref.

For components that will be converted function components. It's easier to go from "no ref" to "some ref" instead of "class instance ref" to "host ref"

The ref is attached to a component class.

E.g. TouchRipple

oliviertassinari
oliviertassinari approved these changes Apr 4, 2019
View reviewed changes
Copy link
Member

@oliviertassinari oliviertassinari left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no strong point of view on this topic. I'm happy to trust your call here.

docs/scripts/buildApi.js
@@ -199,7 +204,11 @@ function run() {
const components = findComponents(path.resolve(rootDirectory, args[2]));

components.forEach(component => {
buildDocs({ component, pagesMarkdown });
buildDocs({ component, pagesMarkdown }).catch(error => {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm surprised it hasn't exploded yet 🚀🌕. This is like 200 concurrent promises 💪.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will celebrate the day uncaught promises will just throw. The current state of async errors in node is really annoying.

@eps1lon eps1lon merged commit f1e2e55 into mui:next Apr 4, 2019
@eps1lon eps1lon deleted the docs/forward-ref branch April 4, 2019 16:15
@eps1lon eps1lon mentioned this pull request Apr 4, 2019
Merged
eps1lon added a commit that referenced this pull request Apr 4, 2019
@eps1lon
[DialogContentText] Test conformance (#15206)
1dee839 
Missing from #15135
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@mbrookes mbrookes mbrookes left review comments

@oliviertassinari oliviertassinari oliviertassinari approved these changes

Assignees
No one assigned
Labels
docs Improvements or additions to the documentation
Projects
None yet
Milestone
v4
Development

Successfully merging this pull request may close these issues.

None yet
4 participants
@eps1lon @mui-pr-bot @mbrookes @oliviertassinari