DevDocs: New "Gutenberg components" section #26314

mmtr · 2018-07-25T21:29:52Z

First task for exposing the Gutenberg components in Calypso and part of #26180.

It creates a new section in the DevDocs that displays the collection of components available in Gutenberg, with documentation explaining how to use them.

Right now, the collection only features the Button component (rest of them will be included in the next PR).

Testing Instructions

Navigate to /devdocs
New section "Gutenberg Components" appears in the sidebar under "Live Docs"
Click on the "Gutenberg Components" section
It redirects to /devdocs/gutenberg-components and a page with a short intro and a collection of component appears
The short introduction has a link that redirects to documentation with more info
The gallery only features the Button components
Click on the Button link
It redirects to a page that displays the same example as before, the code used in the example and README.md file included in the @wordpress/components package for the Button component (https://github.com/WordPress/gutenberg/blob/master/packages/components/src/button/README.md)

Screenshots

matticbot · 2018-07-25T21:29:54Z

Test live: https://calypso.live/?branch=add/devdocs-gutenberg-components

gwwar · 2018-07-25T21:39:09Z

Can you try rebasing from master again? Looks like a number of misc commits on the branch.

mmtr · 2018-07-25T21:47:33Z

yeah, sorry @gwwar. not sure what happened. I'm fixing it

gwwar · 2018-07-25T22:02:45Z

No worries, can happen sometimes with an odd merge, but best to clean it up before it gets too gnarly. A git rebase -i master should clear it up, though it can be painful if you have conflicts on a number of files.

Unless we're working together with another person on a branch, feel free to rebase freely as needed.

mmtr · 2018-07-25T23:08:16Z

everything should be right now @gwwar. thanks for the help!

gwwar · 2018-07-25T23:27:35Z

client/devdocs/sidebar.jsx

@@ -104,6 +104,13 @@ export default class DevdocsSidebar extends React.PureComponent {
 							link="/devdocs/blocks"
 							selected={ this.isItemSelected( '/devdocs/blocks', false ) }
 						/>
+						<SidebarItem


Should we put this under the same feature flag?

I had the same doubt. My main concern is that there are some things we cannot hide even if the feature flag is not enabled:

Gutenberg components in the Components Glossary

Gutenberg components docs in the search:

Because of that and because all the Gutenberg components are actually ready to be used in Calypso (we just need to add more docs explaining how to use the rest of them), I thought that was ok to display this publicly.

But I don't have a strong opinion about this, honestly. If you think that having the readme files available is not a big deal, I can put this under the same feature flag.

gwwar · 2018-07-25T23:34:45Z

client/devdocs/design/search-collection.jsx

+			showEditLink = false;
+		} else {
+			readmeFilePath = `/client/${ section }/${ example.props.readmeFilePath }/README.md`;
+		}


Maybe pull this out into a helper functions?

const shouldShowEditLink = ( section ) => ( section !== 'gutenberg-components' ); const getReadmeFilePath( section, example ) { switch( section ) { case 'design': return `/client/components/${ example.props.readmeFilePath }/README.md`; case 'gutenberg-components'; return `/node_modules/@wordpress/components/src/${ example.props.readmeFilePath }/README.md`; default: return `/client/${ section }/${ example.props.readmeFilePath }/README.md`; } }

gwwar · 2018-07-25T23:35:38Z

client/devdocs/controller.js

@@ -163,6 +163,14 @@ const devdocs = {
 		next();
 	},

+	// Gutenberg C


😄 Don't forget to finish your comment

Oops! 😅 You have not seen anything 🤫

gwwar · 2018-07-25T23:47:24Z

client/devdocs/design/component-playground.jsx

@@ -8,14 +8,15 @@ import classNames from 'classnames';
 import PropTypes from 'prop-types';
 import { LiveProvider, LiveEditor, LiveError, LivePreview } from 'react-live';


Special Sentient Sandwich 💯

https://www.youtube.com/watch?v=2I481MAfLG8

gwwar · 2018-07-25T23:49:12Z

client/devdocs/design/component-playground.jsx


 /**
 * Internal dependencies
 */
 import Button from 'components/button';
 import ClipboardButton from 'components/forms/clipboard-button';
 import DocsExampleWrapper from 'devdocs/docs-example/wrapper';
-import * as playgroundScope from 'devdocs/design/playground-scope';
+import * as playgroundScopeForComponents from 'devdocs/design/playground-scope';


🤔 not sure we can get around not importing both sets.

What about this?

const scope = 'gutenberg-components' === section ? require('@wordpress/components') : require('devdocs/design/playground-scope');

It depends on where we put the requires. For example think of visiting http://calypso.localhost:3000/devdocs/design, then clicking on Gutenberg Components without a browser refresh.

Maybe we could separate the two into two components and then async load?

require loads modules on-demand, so it shouldn't cause any issues when switching from one page to another

gwwar · 2018-07-25T23:51:39Z

client/devdocs/design/component-playground.jsx

+		let scope = playgroundScopeForComponents;
+		if ( 'gutenberg-components' === this.props.section ) {
+			scope = playgroundScopeForGutenbergComponents;
+		}


How about a ternary to avoid the let?

const scope = 'gutenberg-components' === this.props.section ? playgroundScopeForGutenbergComponents : playgroundScopeForComponents;

gwwar · 2018-07-25T23:52:37Z

webpack.config.js

-} else {
-	// jquery is only needed in the build for the desktop app
-	// see electron bug: https://github.com/atom/electron/issues/254
-	webpackConfig.externals.push( 'jquery' );


Ah we'll need to make sure we remove this before change before merge. This is still used by Desktop

Is it still there? I hoped you would refactor paygate to be jQuery free :D

@astralbodies did anything change with regards to the jQuery include? Pretty sure we still need this, right?

it's required by @wordpress/api-fetch, which is a dependency of @wordpress/components

We need to fix it sooner than later! 😅

it's required by @wordpress/api-fetch, which is a dependency of @wordpress/components

I think we should get rid of the jQuery dependency here. The issue in this case is that jQuery in core triggers events on its own events layer, which we can't listen to with native addEventListeners. @gziolo had a good idea: use wp.hooks to relay the jQuery event into a native event, which can then be listened to by api-fetch. Possibly by adding some code to do this as an inline script: https://github.com/WordPress/gutenberg/blob/master/lib/client-assets.php#L154-L161

I think it would also be a good idea to audit what we're depending on jQuery for in Gutenberg in general, and see what can be factored out.

Thanks for the suggestion! I have applied it in WordPress/gutenberg#8311, so as soon as that is merged and published to npm I'll remove the jQuery dependency.

@ehg I have reverted the change and jQuery is not needed now in the bundle. Is this ready to go now?

gwwar · 2018-07-25T23:54:26Z

Overall this looks very promising! Let's see what other folks like @ehg and @mtias think!

Another thing to check is to verify that bundle sizes don't change unexpectedly in http://iscalypsofastyet.com/branch?branch=add/devdocs-gutenberg-components

gziolo · 2018-07-26T08:06:57Z

client/gutenberg-components/button/docs/example.jsx

@@ -0,0 +1,47 @@
+/** @format */


Should we add this code in Gutenberg?

It might be more beneficial to improve docs and add examples inside Gutenberg directly rather than keep them in two places. We can even keep those examples inside README and extract them and auto-build components inside Calypso.

that would be really nice!

gziolo · 2018-07-26T08:11:24Z

Screens look sweet 👍

mmtr · 2018-07-28T09:35:36Z

Another thing to check is to verify that bundle sizes don't change unexpectedly in http://iscalypsofastyet.com/branch?branch=add/devdocs-gutenberg-components

Thanks for this suggestion @gwwar. From what I'm understanding from these tips, I'd say everything is normal. Most of the chunks that have been increased are async loaded. The most relevant change probably is that the vendors build has been increased by 10.9% after including jQuery.

gziolo · 2018-08-02T07:25:48Z

All the latest changes published to npm:

 - @wordpress/api-fetch@1.1.0
 - @wordpress/blocks@1.0.2
 - @wordpress/components@1.1.1
 - @wordpress/core-data@1.0.3
 - @wordpress/editor@1.0.1
 - @wordpress/nux@1.0.2

This includes #8267 and another one which removes jQuery from the list of dependencies:
https://unpkg.com/@wordpress/api-fetch@1.1.0/package.json

Adding helper functions for getting the readme file path and knowing whether to show the edit in GitHub link

Finishing uncompleted comment

Loading only the one needed scope for in the component playground

Adding tests

Getting back jQuery

Adding comment to make clear jQuery is needed temporarily

gwwar

Nice work! ✨ Things are looking really good here.

@ehg or @gziolo did you have any other comments before we land this piece?

gwwar · 2018-08-03T05:18:50Z

assets/stylesheets/_vendor.scss

@@ -2,6 +2,7 @@
 @import '../../node_modules/react-virtualized/styles';
 @import '../../node_modules/draft-js/dist/Draft';
 @import '../../node_modules/notifications-panel/src/boot/stylesheets/style';
+@import '../../node_modules/@wordpress/components/build-style/style';


Hmm, actually any ideas from folks on how to best audit that we're not colliding with existing selectors? Maybe it'd be safer to pull this in devdocs.scss ?

Any opinions here @Automattic/team-calypso ?

Maybe it'd be safer to pull this in devdocs.scss ?

Let's do this for the moment, we're still figuring out SASS imports.

gziolo · 2018-08-03T07:43:07Z

It looks good, I don't have any comments specific for WordPress packages.

ehg · 2018-08-03T11:28:58Z

Other than the issue on where to import the SASS, I think we can land this. Nice work.

mmtr added [Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. [Goal] Gutenberg Working towards full integration with Gutenberg labels Jul 25, 2018

mmtr requested review from ehg, gziolo and gwwar July 25, 2018 21:31

mmtr removed request for ehg, gziolo and gwwar July 25, 2018 21:55

mmtr force-pushed the add/devdocs-gutenberg-components branch 3 times, most recently from ddd1d05 to 20a8b94 Compare July 25, 2018 23:07

mmtr requested review from ehg, gziolo and gwwar July 25, 2018 23:08

gwwar reviewed Jul 25, 2018

View reviewed changes

gziolo reviewed Jul 26, 2018

View reviewed changes

mmtr self-assigned this Jul 26, 2018

mmtr force-pushed the add/devdocs-gutenberg-components branch 2 times, most recently from f5d7d5f to d91d18c Compare July 26, 2018 22:48

mmtr added the DevDocs label Jul 27, 2018

mmtr mentioned this pull request Jul 27, 2018

DevDocs: Gutenberg components - Updating examples #26367

Merged

mmtr mentioned this pull request Jul 28, 2018

Add components examples in README.md files - Part 1 WordPress/gutenberg#8267

Merged

26 tasks

mmtr force-pushed the add/devdocs-gutenberg-components branch from d91d18c to 297d91c Compare August 2, 2018 12:39

mmtr and others added 12 commits August 2, 2018 22:16

DevDocs: New "Gutenberg components" section

ab3f77e

Renaming variable

c17015a

DevDocs: Gutenberg Components

fd6d163

Adding helper functions for getting the readme file path and knowing whether to show the edit in GitHub link

DevDocs: Gutenberg Components

5786acc

Finishing uncompleted comment

DevDocs: Gutenberg Components

4d097d5

Loading only the one needed scope for in the component playground

DevDocs: Gutenberg Components

bd16388

Adding tests

DevDocs: Gutenberg Components

f0e7f31

Getting back jQuery

DevDocs: Gutenberg Components

cbe6d6d

Getting back jQuery

DevDocs: Gutenberg Components

e2eb34f

Adding comment to make clear jQuery is needed temporarily

Update @wordpress/components. jQuery is no longer needed in the build

53b53f4

Update @wordpress/components. jQuery is no longer needed in the build

636a31e

Regenerate npm-shrinkwrap.json

894a537

mmtr force-pushed the add/devdocs-gutenberg-components branch from 297d91c to 894a537 Compare August 2, 2018 20:19

gwwar approved these changes Aug 3, 2018

View reviewed changes

gwwar reviewed Aug 3, 2018

View reviewed changes

Move Gutenberg components styles to from vendor to DevDocs styles

eeef009

mmtr merged commit febda23 into master Aug 3, 2018

mmtr deleted the add/devdocs-gutenberg-components branch August 3, 2018 16:28

matticbot removed the [Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. label Aug 3, 2018

Copons mentioned this pull request Apr 8, 2019

DevDocs: remove Gutenberg components and blocks #32026

Merged

		@@ -8,14 +8,15 @@ import classNames from 'classnames';
		import PropTypes from 'prop-types';
		import { LiveProvider, LiveEditor, LiveError, LivePreview } from 'react-live';

DevDocs: New "Gutenberg components" section #26314

DevDocs: New "Gutenberg components" section #26314

Conversation

mmtr commented Jul 25, 2018 • edited Loading

Testing Instructions

Screenshots

matticbot commented Jul 25, 2018

gwwar commented Jul 25, 2018

mmtr commented Jul 25, 2018

gwwar commented Jul 25, 2018 • edited Loading

mmtr commented Jul 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gwwar Jul 26, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gwwar Jul 25, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gwwar commented Jul 25, 2018

gziolo Jul 26, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Jul 26, 2018

mmtr commented Jul 28, 2018

gziolo commented Aug 2, 2018 • edited Loading

gwwar left a comment

Choose a reason for hiding this comment

gwwar Aug 3, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Aug 3, 2018

ehg commented Aug 3, 2018 • edited Loading

mmtr commented Jul 25, 2018 •

edited

Loading

gwwar commented Jul 25, 2018 •

edited

Loading

gwwar Jul 26, 2018 •

edited

Loading

gwwar Jul 25, 2018 •

edited

Loading

gziolo Jul 26, 2018 •

edited

Loading

gziolo commented Aug 2, 2018 •

edited

Loading

gwwar Aug 3, 2018 •

edited

Loading

ehg commented Aug 3, 2018 •

edited

Loading