[docs] Plan the breaking changes before v1

[oliviertassinari]

More and more people are trying out v1-beta. It's important to engage the community in the breaking changes process.

[mbrookes]

"For users, test coverage is hard to raise..."

[oliviertassinari]

We will recycle an old codemode for this breaking.
I won't have the courage to do it by hand on my codebase.
Better scaling it for everybody.
https://github.com/mui-org/material-ui/tree/v1-beta/packages/material-ui-codemod#import-path.

[yuchi]

Personally I really love the Component Injection API. Most libraries recently implement a mix of the two by letting the developer use either a render prop or a component prop. Most also actually implement the Component Injection API while still using render as the prop name.

For example see how react-tunnels actually uses the render prop.

[oliviertassinari]

https://github.com/final-form/react-final-form#rendering

Method	How it is rendered
component prop (CI)	return React.createElement(this.props.component, props)
render prop	return this.props.render(props)
a render function as children	return this.props.children(props)

Some thoughts:

• The component injection API (CI) has one important limitation ⚠️. When the parent renders, you create a new component, which unmounts all the children. This force you to move the component creation outside of the render method. It's friction. We have documented it in: https://material-ui.com/guides/composition/#component-property

• I think that we should encourage people using "a render function as children" over "render prop". It's the same move React did with the new Context API. I'm sure they have made this design choice carefully. I don't know their motivations but mines are:

  • the closing </ helps with code readability.
  • the render property is unnecessary boilerplate.

  It doesn't mean we can't support both.

• "component prop" and "a render function as children" have both interesting use cases.

[yuchi]

What I really love is the terseness of component="nav" instead of render={props => <nav {...props} />} or …> {props => <nav {...props} />} </….

I’d be totally ok if you moved to an hybrid.

What would happen if both component and a render prop is passed?

[oliviertassinari]

This breaking change point was way more about the transition property and Actions property of the Table than revisiting the problem solved by the root component property.

[TroySchmidt]

So excited this is coming out of beta! I think all the breaking changes make sense and will only help the quality. The CSS one seems a little confusing to me, but I am sure once I see more documentation on it, it will make more sense. Great job!

[pureliumy]

These changes make it more clear, especially love the CSS one. But it still has many limitations in CSS area with JSS, we can't delete the empty checked class for instance. Also I can't write my own keyframe animation and make it work in component.