[docs] Add utils section, document transitions

[mbrookes]

Also move modals & popover docs to utils
Clean up API inheritance docs

Closes #10153

[oliviertassinari]

@mbrookes Great job!

[mbrookes]

@oliviertassinari One thing I realised when working on this is that the name of the Collapse component is "backwards". All the other component names describe what the transition does when it is transitioning in (or can be used bidirectionally.

I propose we rename Collapse to Expand.

[oliviertassinari]

I propose we rename Collapse to Expand.

Some benchmark:

• https://getbootstrap.com/docs/4.0/components/collapse/
• https://www.npmjs.com/search?q=collapse vs https://www.npmjs.com/search?q=expand

Collapse seems more "into the head" of people.

[oliviertassinari]

ll the other component names describe what the transition does when it is transitioning in

It's that also true with Fade?

[mbrookes]

Fade can be used bidirectionally - "fade in", "fade out". I can't think of anything better.

[mbrookes]

A better benchmark:

Generic:

• https://www.google.co.uk/search?q=collapse+animation "About 2,380,000 results"
• https://www.google.co.uk/search?q=expand+animation "About 25,300,000 results"

Material Design:

• https://www.google.co.uk/search?q=collapse+animation+material+design "About 961,000 results"
• https://www.google.co.uk/search?q=expand+animation+material+design "About 1,660,000 results"

JS:

• https://www.google.co.uk/search?q=collapse+animation+js "About 325,000 results"
• https://www.google.co.uk/search?q=expand+animation+js "About 1,210,000 results"

CSS:

• https://www.google.co.uk/search?q=collapse+animation+css "About 312,000 results"
• https://www.google.co.uk/search?q=expand+animation+css "About 576,000 results"

[oliviertassinari]

I'm against this change:

• Polymer collapse
• Bootstrap collapse
• Ant Design collapse
• Blueprint collapse

[mbrookes]

Then shouldn't the in prop's behaviour be reversed? At the moment when Collapse is true, the component is expanded, which is kinda backwards.

[oliviertassinari]

Then shouldn't the in prop's behaviour be reversed?

Won't that makes it even more confusion? I would expect my element to be mounted when in is true, not the opposite 🤔.

[mbrookes]

Which is why I originally proposed changing the name of the component - it does the opposite of what it says.

So, change Grow to Shrink instead ? 😄

[oliviertassinari]

What about Zoom? The wording should allow people to visualise the type of animation. I don't think that the "in" or "out" aspect if it matter. The in property has already this responsability. My interpretation of the current wordings:

• Fade "out"
• Grow "in"
• Collapse "out"
• Slide "in"/"out"
• Zoom "in"

[mbrookes]

"Fade in / out"
"Grow" (in)
"Collapse" (out)
"Slide in / out"
"Zoom in / out"