Block API: Add block styles variations API #7362

youknowriad · 2018-06-19T08:39:30Z

This is the first step towards #783

It adds a transforms.styles Block API to support style variations per block. It works by adding an is-style-{styleName} className to the custom className per block.

This PR replaces the style variations of the quote block by this new API. It keeps the UI similar for now.

Testing instructions

Add a quote block
Switch the quote style

Visuals

paulwilde · 2018-06-19T09:52:27Z

It would be nice if rather than having a fixed is-style-{styleName} naming convention for each style, if the option existed for assigning a specific class for each style within the transforms.styles API.

This would then allow for this API to be utilised for existing websites rather than having to adapt.

youknowriad · 2018-06-19T10:01:37Z

This would then allow for this API to be utilised for existing websites rather than having to adapt.

I wonder if it's a good idea to adapt the API to existing websites. I tend to think while we have the opportunity to change things, we should seek for the best API instead and a naming convention seems better to me for the moment, it makes it clear where the classname comes from.

Also, this doesn't break anything since we have the "deprecated versions" API so block that upgrade to use this new API can adapt pretty easily without breakage.

gziolo · 2018-06-19T11:00:32Z

core-blocks/quote/index.js

@@ -66,6 +60,10 @@ export const settings = {
 	attributes: blockAttributes,

 	transforms: {
+		styles: [


This is a very expected API 👍

mtias · 2018-06-19T11:37:05Z

editor/components/block-styles/index.js

+
+	return (
+		<Toolbar controls={ styles.map( ( variation ) => ( {
+			icon: variation.icon,


I don't think we'd want to attach the style variation to an icon, since we are likely to drop that approach for quotes. I imagine initially we'd just show a custom button in Quote toolbar to toggle between the registered styles. Once we build the proper UI for style variations we'd just remove the toolbar item.

chrisvanpatten · 2018-06-19T12:32:49Z

Two things that are more vague related thoughts than anything else…

Some blocks might want a block style variation to change more than just a CSS class. Of course I don't think that's necessarily the API's job to worry about handling all those cases: as long as the block's style value is available outside a className context (which it appears to be), it should be easy enough for the block to handle those conditions and transform everything it wants to transform.
Right now it looks like the styles have an icon parameter. Would that be compatible with @karmatosed's amazing mockup here where the icon is more like an image?

EDIT: And also worth noting that I am super super excited for this functionality :)

youknowriad · 2018-06-19T12:38:56Z

@mtias @chrisvanpatten yes, the icon parameter is here to keep the same UI as today but maybe we should continue the UI work in this PR to get rid of this parameter.

Some blocks might want a block style variation to change more than just a CSS class. Of course I don't think that's necessarily the API's job to worry about handling all those cases: as long as the block's style value is available outside a className context (which it appears to be), it should be easy enough for the block to handle those conditions and transform everything it wants to transform.

In general, I think if extending block requires more than adding a className or buttons to update existing block attributes, I tend to think we should probably think about creating a separate block transformable to the current block using the transforms API instead of trying to extend the existing blocks.

chrisvanpatten · 2018-06-19T13:25:21Z

In general, I think if extending block requires more than adding a className or buttons to update existing block attributes, I tend to think we should probably think about creating a separate block transformable to the current block using the transforms API instead of trying to extend the existing blocks.

I had a long response typed out but it kind of felt unnecessary haha. Ultimately I think if folks need to change markup for a core block, they should absolutely be encouraged to create a custom block and leverage the existing transforms API. However I think it's also fair that custom blocks, who use this API to provide alternate designs for a block, may need small markup changes between variants within a single block that don't warrant creating an entirely separate block.

However, as long as the style format attribute is available to the custom block, the API doesn't need to worry about anything. It just manages the UI and the attribute, and lets the custom block determine how that information impacts the rendered and saved content, beyond adding it as a class name. It seems like that's already happening here, however, so I think everything's in good shape :)

mtias · 2018-06-19T13:32:02Z

who use this API to provide alternate designs for a block, may need small markup changes between variants within a single block that don't warrant creating an entirely separate block.

The other problem is this introduces too many variations that would be hard to account in validation stages, particularly if the plugin extending a core block is disabled — the block would become invalid, and we wouldn't have knowledge of which transformations to apply.

Restricting variation of variants to classes would allow people to extend blocks without the overhead of creating their own, but without suffering from invalidation hurdles.

chrisvanpatten · 2018-06-19T13:33:57Z

@mtias I'm not referring to extending existing blocks, only to custom blocks. I agree completely that if you're extending an existing block, you should be limited to class names. But authors of completely custom blocks might want access (or even need access, in the case of server-rendered blocks) to this attribute.

mtias · 2018-06-19T13:38:34Z

Oh, sure, the attribute should totally be exposed as it'd be useful in many scenarios.

youknowriad · 2018-06-21T11:19:56Z

Ok, so I've pushed this further and implemented the UI proposed by @karmatosed

Instead of using an "example" to preview the style, I'm using the current block's content.

mtias · 2018-06-21T11:54:21Z

Instead of using an "example" to preview the style, I'm using the current block's content.

This is clever, good call.

mtias · 2018-06-21T12:06:03Z

There is one more thing here that I'd like to ponder, which is how it could relate to the "additional CSS class" panel.

I'm thinking it could be neat to let user write a class and click a button to register that class as a block style variation:

Thinking further, we could even let you write CSS targeting this specific class, and we'd apply it to the block / miniature automatically.

All this is definitely not for this issue :)

youknowriad · 2018-06-22T08:25:49Z

Updated the PR, I used a grid view to the block transforms similar to the inserter and added an e2e test. Should we land this an iterate?

gziolo · 2018-06-22T08:27:23Z

test/e2e/specs/style-variation.test.js

+
+		// Check the content
+		const content = await getHTMLFromCodeEditor();
+		expect( content ).toMatchSnapshot();


How much work it would be to add validation if the class name starting with is-type* has been applied to the block's HTML code?

You mean a regex to catch the className or something?

I mean we can add it but we do have unit tests to test the functions applying and retrieving those classNames.

Probably XPath expression offered by Puppetter API would be sufficient, but yes, this is what I thought about.

It's a blurry territory between e2e and unit tests, if it is covered already then it's fine to skip this suggestion.

mtias · 2018-06-22T08:49:15Z

Pushed change to use the small block icon with colors and drop the down arrow.

mtias · 2018-06-22T09:05:28Z

When the popover switches to the top, some of the containing elements break out of it:

mtias · 2018-06-22T09:24:48Z

Closes #7227.

youknowriad · 2018-06-22T11:30:55Z

@mtias Did you fix the extra border showing up when the popover switches to the top? I can't reproduce in my testing.

mtias · 2018-06-22T14:16:32Z

I didn't.

karmatosed · 2018-06-22T20:35:19Z

This looks really great so far thanks for all the work on it.

One thing I did wonder about is there anything we can do about the formatting on the style variants?

Above you can see what happens with the default text and it looks weird to have one so small and the other on two lines.

youknowriad · 2018-06-22T20:45:51Z

@karmatosed What we can probably do is to give a minimum width to the preview and use overflow: hidden to crop it when the available width is smaller than this min width. This would avoid returning to the line too often.

Though, I think no matter what we do, we'd still have styling issues because the blocks are not meant to be shown in such a small area.

chrisvanpatten · 2018-06-25T12:05:42Z

What's the a11y impact of having the live nested block previews, vs an SVG or raster image? Do screen readers try to read out or navigate the blocks?

Sorry about the typo.

- Bug: the body text was not the same gray as the title. This fixes that. - The new Dots separator style is simpler, smaller, better centered, and uses the same color as the text. - The wide separator style is now thinner.

- Rename remaining instance of "asterisks" to "dots" - Move default separator style to theme.scss so it can be opted into - Scope default style so it doesn't bleed into dots and wide styles - Refine dots and wide styles to better work on frontend

youknowriad · 2018-06-27T12:09:15Z

I rebased. I'm seeing intermittent e2e test failures preventing the merge. Let's see how it goes this time.

kjellr · 2018-06-27T12:25:06Z

Note, the wide style here is limited due to a bug in the gutenberg starter theme where we simply have to remove it, I've verified that it's not an issue with the theme.scss file, or anything that Gutenberg provides.

@jasmussen — I've got you covered there. 🙂WordPress/gutenberg-starter-theme#64 can be merged in to fix that.

aduth · 2018-08-17T21:23:46Z

test/e2e/specs/__snapshots__/style-variation.test.js.snap

+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`adding blocks Should switch the style of the quote block 1`] = `
+"<!-- wp:quote {\\"className\\":\\" is-style-large\\"} -->


Thinking we might have the tendency to be not be giving close attention to the snapshots 😅 Note the leading whitespace, and the double space in the next line.

Happy they exist though, as I believe they may have captured a legitimate issue in #9105.

aduth · 2018-10-22T17:48:53Z

editor/components/block-styles/index.js

+		<div className="editor-block-styles">
+			{ styles.map( ( style ) => {
+				const styleClassName = replaceActiveStyle( className, activeStyle, style );
+				/* eslint-disable jsx-a11y/click-events-have-key-events */


This is an unfortunate instance of blindly disabling a rule for which its entire purpose is to protect against the thing we've introduced here.

https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/click-events-have-key-events.md

youknowriad added the [Feature] Block API API that allows to express the block paradigm. label Jun 19, 2018

youknowriad self-assigned this Jun 19, 2018

youknowriad requested review from mtias and gziolo June 19, 2018 08:39

gziolo reviewed Jun 19, 2018

View reviewed changes

mtias reviewed Jun 19, 2018

View reviewed changes

youknowriad force-pushed the add/style-variations-api branch from 33efa85 to 6173aa8 Compare June 21, 2018 11:19

gziolo added this to the 3.2 milestone Jun 21, 2018

gziolo reviewed Jun 22, 2018

View reviewed changes

karmatosed self-requested a review June 22, 2018 20:35

jasmussen and others added 8 commits June 27, 2018 13:07

Rename CSS class to utilize is-active.

91c8900

Sorry about the typo.

Showing style variation labels

616731d

Polish the separator styles

295b608

- Bug: the body text was not the same gray as the title. This fixes that. - The new Dots separator style is simpler, smaller, better centered, and uses the same color as the text. - The wide separator style is now thinner.

Fix grid items width

052922c

Use proper label names for quote styles.

252a3fc

Polish separator styles for frontend

837295a

- Rename remaining instance of "asterisks" to "dots" - Move default separator style to theme.scss so it can be opted into - Scope default style so it doesn't bleed into dots and wide styles - Refine dots and wide styles to better work on frontend

Add button outline style.

8c0db3a

Fix unit tests (Block Switcher without blocks)

d720cab

youknowriad force-pushed the add/style-variations-api branch from 8dcfed4 to d720cab Compare June 27, 2018 12:08

youknowriad merged commit e197ba0 into master Jun 27, 2018

youknowriad deleted the add/style-variations-api branch June 27, 2018 12:17

youknowriad mentioned this pull request Jun 27, 2018

Create unified UI for block variants #783

Closed

kjellr mentioned this pull request Jun 27, 2018

Remove max-width for separators. WordPress/gutenberg-starter-theme#64

Merged

This was referenced Jun 29, 2018

Move "opinionated" Gutenberg block styles to theme.scss #7624

Merged

Consider whether Pullquote should be a separate block, a style of quotes, or vice versa #5947

Closed

ZebulanStanphill mentioned this pull request Jun 29, 2018

Blocks: Bring transforms into block library #7227

Closed

karmatosed mentioned this pull request Jul 3, 2018

Add text color option to Heading block #6012

Closed

talldan mentioned this pull request Jul 10, 2018

Unify the block toolbar for all text blocks #3785

Closed

mrwweb mentioned this pull request Jul 13, 2018

TinyMCE styleselect danielbachhuber/gutenberg-migration-guide#10

Closed

Soean mentioned this pull request Jul 23, 2018

Docs: Block Style Variations #8145

Closed

aduth reviewed Aug 17, 2018

View reviewed changes

ZebulanStanphill mentioned this pull request Aug 24, 2018

Block Transforms should be more discoverable/obvious #9127

Closed

mtias mentioned this pull request Sep 1, 2018

🖍 A Block Style System #9534

Closed

This was referenced Oct 15, 2018

Block: Separator style class #10569

Closed

Cannot activate block styles via keyboard #10908

Closed

aduth reviewed Oct 22, 2018

View reviewed changes

greatislander mentioned this pull request Nov 12, 2018

Allow custom style variation classNames #11763

Open

eric7186 mentioned this pull request Jan 3, 2022

Global style Utility Classes #37494

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Block API: Add block styles variations API #7362

Block API: Add block styles variations API #7362

youknowriad commented Jun 19, 2018 •

edited by mtias

Loading

paulwilde commented Jun 19, 2018

youknowriad commented Jun 19, 2018

gziolo Jun 19, 2018

mtias Jun 19, 2018

chrisvanpatten commented Jun 19, 2018 •

edited

Loading

youknowriad commented Jun 19, 2018

chrisvanpatten commented Jun 19, 2018 •

edited

Loading

mtias commented Jun 19, 2018

chrisvanpatten commented Jun 19, 2018

mtias commented Jun 19, 2018

youknowriad commented Jun 21, 2018 •

edited

Loading

mtias commented Jun 21, 2018

mtias commented Jun 21, 2018

youknowriad commented Jun 22, 2018

gziolo Jun 22, 2018

youknowriad Jun 22, 2018

gziolo Jun 22, 2018

gziolo Jun 22, 2018

mtias commented Jun 22, 2018

mtias commented Jun 22, 2018

mtias commented Jun 22, 2018

youknowriad commented Jun 22, 2018

mtias commented Jun 22, 2018

karmatosed commented Jun 22, 2018

youknowriad commented Jun 22, 2018

chrisvanpatten commented Jun 25, 2018

youknowriad commented Jun 27, 2018

kjellr commented Jun 27, 2018

aduth Aug 17, 2018

aduth Oct 22, 2018

Block API: Add block styles variations API #7362

Block API: Add block styles variations API #7362

Conversation

youknowriad commented Jun 19, 2018 • edited by mtias Loading

Visuals

paulwilde commented Jun 19, 2018

youknowriad commented Jun 19, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisvanpatten commented Jun 19, 2018 • edited Loading

youknowriad commented Jun 19, 2018

chrisvanpatten commented Jun 19, 2018 • edited Loading

mtias commented Jun 19, 2018

chrisvanpatten commented Jun 19, 2018

mtias commented Jun 19, 2018

youknowriad commented Jun 21, 2018 • edited Loading

mtias commented Jun 21, 2018

mtias commented Jun 21, 2018

youknowriad commented Jun 22, 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

mtias commented Jun 22, 2018

mtias commented Jun 22, 2018

mtias commented Jun 22, 2018

youknowriad commented Jun 22, 2018

mtias commented Jun 22, 2018

karmatosed commented Jun 22, 2018

youknowriad commented Jun 22, 2018

chrisvanpatten commented Jun 25, 2018

youknowriad commented Jun 27, 2018

kjellr commented Jun 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad commented Jun 19, 2018 •

edited by mtias

Loading

chrisvanpatten commented Jun 19, 2018 •

edited

Loading

chrisvanpatten commented Jun 19, 2018 •

edited

Loading

youknowriad commented Jun 21, 2018 •

edited

Loading