Add Gutenberg Stories #590

Josh68 · 2020-04-03T22:48:56Z

Overview

This PR adds a single stories file containing un-styled stories for readily theme-able Gutenberg blocks. These are blocks that generate markup with added wp-block- classes.

The examples aim to provide ample detail for understanding variations that may be generated using the block editor controls. However, it is not exhaustive, and the API for each block is not easily discoverable. In almost all cases, the markup and classes added to examples is based on discovery using the editor on a local Wordpress installation.

Screenshots

Testing

View the preview theme
See cloudfour.com-wp issue #450
Ensure all non-widget core blocks with a 🎨 icon have a story
Provide feedback regarding copy, examples (easily updated), and any other suggestions

Addresses cloudfour.com-wp issue #450

/CC @tylersticka @derekshirk

Josh68 · 2020-04-04T00:12:36Z

Added @derekshirk as a potential reviewer, but I think @tylersticka needs to be the primary. If I should add any one else (or remove Derek), let me know.

Paul-Hebert

This is looking good Josh!

I don't have a ton of context on this work but I was curious to see how this was set up. Because of that I'm not going to approve or request changes but I left some nits and questions inline.

I wonder if it would be possible to add a class knob so we could explore adding pattern library classes to these blocks? e.g. making the button block have the c-button class? Though that may well be outside the scope of this PR.

Anyways, nice job putting this together! It was interesting to see the various blocks Gutenberg provides.

Paul-Hebert · 2020-04-06T16:56:08Z

src/third-party/gutenberg.stories.mdx

+## Button
+
+The button block creates one or more `div`s with class `wp-block-button`, each containing
+an `a` element with a class of `wp-block-button__link`.


It's weird that this doesn't use <button>. 🤔

That's what Gutenberg gives us by default?

You got it. In this case, button is meant to be a link, either to directly get a media asset or navigate to its attachment page. It could probably use a better name.

The intent here is to add call-to-action style links to a post. The containers exist for layout, the links to link to that content. I think in this case the naming of this pattern is probably more confusing to web developers than to end users.

I can update the description, if that seems worthwhile.

Paul-Hebert · 2020-04-06T16:59:04Z

src/third-party/gutenberg.stories.mdx

+            >
+          </blockquote>
+          <iframe
+            title=""Elements” — wp-themes.com"


Nit: looks like these opening quotation marks got messed up somehow

Thanks. This markup was actual output from embedding wp-themes content, so not sure why it came out that way.

Side note: I imagine we may have discussions about what sources we keep or change in this PR, but my goal was to try to offer relatively complete examples with content, and wordpress.org, unfortunately, does not itself offer much good content to use in stories like this.

Paul-Hebert · 2020-04-06T17:00:48Z

src/third-party/gutenberg.stories.mdx

+          class="wp-image-130"
+          srcset="
+            https://s.w.org/images/core/5.3/MtBlanc1.jpg         500w,
+            https://s.w.org/images/core/5.3/MtBlanc1-300x225.jpg 300w


It's cool that this is set up to use srcset!

Paul-Hebert · 2020-04-06T17:01:25Z

src/third-party/gutenberg.stories.mdx

+              (__)\\       )\\\/\\
+                  ||----w |
+                  ||     ||
+      </pre>`}


Paul-Hebert · 2020-04-06T17:02:39Z

src/third-party/gutenberg.stories.mdx

+`wp-block-pullquote`.
+
+[Color controls](#color-settings) allow the setting of pre-defined or custom `background-color` and
+text `color`. A styles control adds one of two wrapper classes, `is-style-default` or


Nit: sometimes this is referred to as styles control and sometimes it's referred to as style controls. It would be nice to be consistent.

I updated for consistency

Paul-Hebert · 2020-04-06T17:03:56Z

src/third-party/gutenberg.stories.mdx

+          class="wp-block-spacer"
+        ></div>
+      <p>Content after spacer.</p>`}
+  </Story>


Weird... is this meant to control margins in our WYSIWYG editor? Hopefully we can avoid this and use our margin utilities.

Yeah, this is simply a way to add a random amount of vertical space, but potentially with additional styling. And it's probably something that won't get used, but I don't know. In general, I don't know whether we might un-register some of the default blocks in our theme to prevent their use. TBD.

…cause the heading for these controls is 'Styles').

Josh68

This is looking good Josh!

I don't have a ton of context on this work but I was curious to see how this was set up. Because of that I'm not going to approve or request changes but I left some nits and questions inline.

Thanks for the feedback, @Paul-Hebert. I'm curious to see how the pattern library and Gutenberg end up coming together.

I wonder if it would be possible to add a class knob so we could explore adding pattern library classes to these blocks? e.g. making the button block have the c-button class? Though that may well be outside the scope of this PR.

I'd like to see what @tylersticka thinks about this idea. All blocks do have a place to enter arbitrary class names, so this may make sense.

tylersticka · 2020-04-07T16:19:47Z

src/third-party/gutenberg.stories.mdx

+
+# WordPress Gutenberg Blocks
+
+The Wordpress Gutenberg editor is a block-based page builder. The editor comes with


Can we link to some documentation somewhere in here?

Added a link to the main page on wordpress.org, but if you'd like to link to something more specific to development, let me know.

tylersticka · 2020-04-07T16:20:40Z

src/third-party/gutenberg.stories.mdx

+<Preview>
+  <Story name="core/audio" height="150px">{`
+    <figure class="wp-block-audio type">
+      <audio controls="" src=""></audio>


Can we add a short demo audio file?

tylersticka · 2020-04-07T16:21:45Z

src/third-party/gutenberg.stories.mdx

+## Button
+
+The button block creates one or more `div`s with class `wp-block-button`, each containing
+an `a` element with a class of `wp-block-button__link`.


The intent here is to add call-to-action style links to a post. The containers exist for layout, the links to link to that content. I think in this case the naming of this pattern is probably more confusing to web developers than to end users.

tylersticka · 2020-04-07T16:23:10Z

src/third-party/gutenberg.stories.mdx

+    {`<pre class="wp-block-code">
+        <code>
+          // A "block" is the abstract term used
+          // to describe units of markup that,
+          // when composed together, form the
+          // content or layout of a page.
+          registerBlockType( name, settings );
+        </code>
+      </pre>`}


Whitespace should be stripped, as currently the pattern is showing a bunch of leading spaces.

Updated to remove whitespace. That was a formatting error on my end.

#590 (comment)

Updated again. I eschewed using Prism, but can add if you like.

tylersticka · 2020-04-07T16:23:51Z

src/third-party/gutenberg.stories.mdx

+The code block adds the class `wp-block-code` to a `pre` tag wrapping content inside
+`code` tags.


I'm not sure it's necessary to describe in prose the markup structure and attribute contents for each pattern?

I wonder if we should discuss my overall approach to story descriptions here. I didn't think mine was necessarily the best, but felt like some basic introduction was a good idea for all of them, and that for the simplest patterns, this approach was just a way to be consistent across descriptions. I realize that for something like the code block, probably no description is needed at all.

In this case, would you even include a description, and if so, would it just be something like Provides a block-level class name for styling code snippets?

tylersticka · 2020-04-07T16:25:38Z

src/third-party/gutenberg.stories.mdx

+          // A "block" is the abstract term used
+          // to describe units of markup that,
+          // when composed together, form the
+          // content or layout of a page.
+          registerBlockType( name, settings );


I recommend choosing one of the code samples from our code block story instead of on that is 90% comment. (You can view different examples via a knob.)

#590 (comment)

tylersticka · 2020-04-07T16:27:02Z

src/third-party/gutenberg.stories.mdx

+<Preview>
+  <Story name="core/file" height="100px">
+    {`<div class="wp-block-file">
+        <a href="https://i1.wp.com/wordpress.org/news/files/2020/03/Squares.jpg"


Let's avoid hotlinking to images in favor of storing some examples in our project. There should be plenty if you browse around our articles.

For some reason, I avoided uploading assets into the repo (wasn't sure that was OK), but thought about the drawbacks of hotlinking. I will look to add images, audio, and video, as needed, because I think they're needed.

I've localized all previously hotlinked assets under static/media

Josh68 · 2020-04-08T20:56:33Z

@tylersticka, please look at the updated audio and button descriptions and let me know if these provide the level of detail you'd like (avoiding too much prose description of the default generated markup). I will address others once you provide feedback on those.

I was assuming documenting some of the options that controls offer still made sense, but if you still think that's overkill, I can pare down further.

I think I've addressed all other comments so far. Feel free to resolve comment threads you've reviewed, if it helps. Thanks

Josh68 added 19 commits April 1, 2020 17:09

Start to add Gutenberg blocks to a new story

77758c0

Add initial gallery block, remove local-install specific file urls

d072c79

Update gallery block

5c47107

Adds button block story

689befb

Revise introductory text

0ac3483

Adds code block

3b4bfed

Add columns block

fc1edf5

Add cover block

38332a2

Add group block

2415078

Adds media-text block

ab1f0b8

Fix media text block and add preformatted

aa8e236

Adds pullquote block

87b8ccd

Updates some formatting

0fe2d4d

Adds table and separator blocks

0713427

Adds verse block

020adf9

Adds audio block

000602b

Adds embed block story

4bc9e6d

Adds file and spacer blocks

abed648

Reorganizes blocks alphabetically, adjusts heights, fixes a few things

73ec593

Josh68 self-assigned this Apr 3, 2020

Josh68 added 3 commits April 3, 2020 16:25

Move general style and color controls description to beginning of file

a7e42fa

Add inline link to color settings

443f2d4

Add inline link to color settings

107c92a

Josh68 requested a review from tylersticka April 3, 2020 23:42

Merge remote-tracking branch 'origin/v-next' into add-gutenberg-stories

e00c06b

Josh68 changed the title ~~[DRAFT] Add Gutenberg Stories~~ Add Gutenberg Stories Apr 3, 2020

Fix linting issues

525afbd

Josh68 marked this pull request as ready for review April 4, 2020 00:11

Josh68 requested a review from derekshirk April 4, 2020 00:11

Paul-Hebert reviewed Apr 6, 2020

View reviewed changes

Josh68 added 2 commits April 6, 2020 15:05

Fix invalid nested quotes

03cb57b

Change 'style controls' to 'styles controls,' for consistency (and be…

9891890

…cause the heading for these controls is 'Styles').

Josh68 commented Apr 6, 2020

View reviewed changes

Merge remote-tracking branch 'origin/v-next' into add-gutenberg-stories

96a9e9f

tylersticka reviewed Apr 7, 2020

View reviewed changes

Josh68 added 8 commits April 8, 2020 08:51

Add link to main Gutenberg docs

8d84c4d

Remove extraneous whitespace from 'core/code' story

718579b

Add some local media assets

1bd2c30

Merge remote-tracking branch 'origin/v-next' into add-gutenberg-stories

3f5d368

Reuse code demo

ccb4dec

Stop hotlinking images

a741c6a

Localize one more hotlinked image

ac77cfe

Update audio and button descriptions, for review

5afc7c1

Josh68 requested a review from tylersticka April 8, 2020 20:56

Josh68 added 4 commits April 8, 2020 14:30

Fix for prettier linting error

877d348

Merge remote-tracking branch 'origin/v-next' into add-gutenberg-stories

7863fee

Merge remote-tracking branch 'origin/v-next' into add-gutenberg-stories

2e3f28d

Merge remote-tracking branch 'origin/v-next' into add-gutenberg-stories

a39592b

tylersticka approved these changes Apr 9, 2020

View reviewed changes

Josh68 merged commit c955c60 into v-next Apr 9, 2020

Josh68 deleted the add-gutenberg-stories branch April 9, 2020 23:45

tylersticka mentioned this pull request May 18, 2020

Style critical Gutenberg block markup #710

Closed

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Gutenberg Stories #590

Add Gutenberg Stories #590

Josh68 commented Apr 3, 2020 •

edited

Loading

Josh68 commented Apr 4, 2020

Paul-Hebert left a comment

Paul-Hebert Apr 6, 2020

Josh68 Apr 6, 2020

tylersticka Apr 7, 2020

Josh68 Apr 8, 2020

Paul-Hebert Apr 6, 2020

Josh68 Apr 6, 2020

Paul-Hebert Apr 6, 2020

Paul-Hebert Apr 6, 2020

Paul-Hebert Apr 6, 2020

Josh68 Apr 6, 2020

Paul-Hebert Apr 6, 2020

Josh68 Apr 6, 2020

Josh68 left a comment

tylersticka Apr 7, 2020

Josh68 Apr 8, 2020

tylersticka Apr 7, 2020

Josh68 Apr 8, 2020

tylersticka Apr 7, 2020

tylersticka Apr 7, 2020

Josh68 Apr 8, 2020

Josh68 Apr 8, 2020

tylersticka Apr 7, 2020

Josh68 Apr 8, 2020

tylersticka Apr 7, 2020

Josh68 Apr 8, 2020

tylersticka Apr 7, 2020

Josh68 Apr 8, 2020

Josh68 Apr 8, 2020

Josh68 commented Apr 8, 2020


		# WordPress Gutenberg Blocks

		The Wordpress Gutenberg editor is a block-based page builder. The editor comes with

		The code block adds the class `wp-block-code` to a `pre` tag wrapping content inside
		`code` tags.

Add Gutenberg Stories #590

Add Gutenberg Stories #590

Conversation

Josh68 commented Apr 3, 2020 • edited Loading

Overview

Screenshots

Testing

Josh68 commented Apr 4, 2020

Paul-Hebert left a 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

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

Josh68 left a 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

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

Josh68 commented Apr 8, 2020

Josh68 commented Apr 3, 2020 •

edited

Loading