We favor functional components, it should stay as it was. Using Component class with lifecycle methods is more complex, requires more code and might be subject of change in the future. Actually, React 16.3 is a great example how those API can get deprecated.

got it!

This example can also be expressed as functional component wrapped with withState higher-order component (HOC). I believe it is code this way in the existing codebase.

Can we also include import statement to make it possible to extract code as is and run it without any modifications?

Yeah, that would be great but I'm afraid I have a limitation here.

I'm using react-live for compiling and running these snippets of code in real time, so we avoid to change our build process.

That forces us to import the dependencies outside the snippets in order to define the scope needed by react-live to run the extracted code.

Anyway, I think we should maintain them in the examples in order to provide documentation as complete as possible. We can always ignore them when running the snippets (you can check how I'm handling that here: https://github.com/Automattic/wp-calypso/pull/26367/files#diff-d0c3bde7d6504cb5de69c0488b877342R36)

Out of curiosity, don't you need to export those components to be able to use them in Calypso devdocs? For the purpose of docs it's fine as is. However, if that would help, don't hesitate to add export statements.

react-live doesn't need it. As long as you inject a string with either a component class, a functional component or JSX code, it will be able to render it: https://react-live.kitten.sh/

How do you feel about using the version which calls render?

const Wrapper = ({ children }) => (
  <div style={{
    background: 'papayawhip',
    width: '100%',
    padding: '2rem'
  }}>
    {children}
  </div>
)

const Title = () => (
  <h3 style={{ color: 'palevioletred' }}>
    Hello World!
  </h3>
)

render(
  <Wrapper>
    <Title />
  </Wrapper>
)

3rd example on the demo page.

It's not trivial.

That render call should be performed in Calypso (it doesn't make sense to include it in the Gutenberg examples), but how Calypso can know what are the components that need to be rendered?

For rendering the Autocomplete example it should use render( <FreshFruitAutocomplete /> ), but for the Button example it should use render( <MyButton /> ). But there is no way for getting this in a dynamic way.

Maybe we can use always the My<ComponentName> pattern and assume that in Calypso. But we need to be sure that the name of the variables doesn't change in the example or we'll broke the Calypso's DevDocs. What do you think?

I missed that comment. It seems like a good pattern, let's discuss further in the 2nd part of the PR where those changes are applied.

To avoid some hassle with adding those equality signs, you can also simply use:

# BaseControl

We use this form in README.md files in the root folder of each npm package.

Gutenberg, it's a community project. Let's use https://wordpress.org/ instead 😄

I think it would make sense to include checked property, too. Otherwise this example won't be very useful. In such case onChange would need to be update. We can use something similar to what we have in ClipboardButton using withState.

It might to make it easier to understand if we would add some description inside text prop, .e.g.: Text to be copied..

Missing spaces after [ and before ], sorry about WordPress conventions 😄

const My KeyboardShortcuts = ?

It might be better to put MenuItem in here:

<MenuGroup label="Settings">
	<MenuItem>Setting 1</MenuItem>
	<MenuItem>Setting 2</MenuItem>
</MenuGroup>

This is how it should be used in general.

const MyMenuItem = ?

const MyMenuItemsChoice = ?