Block Styles: Extend block style variations as mechanism for achieving section styling #57908
Conversation
aaronrobertshaw
added
[Type] Experimental
aaronrobertshaw
force-pushed
the
add/section-styling-via-block-styles
branch
from
2ab4d24
to
ae56a2e
Compare
aaronrobertshaw
force-pushed
the
add/section-styling-via-block-styles
branch
from
ae56a2e
to
1949ae1
Compare
|
This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress. If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged. If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack. Thank you! ❤️ View changed files❔ lib/block-supports/block-style-variations.php ❔ phpunit/block-supports/block-style-variations-test.php ❔ phpunit/data/themedir1/block-theme-child-with-block-style-variations/style.css ❔ phpunit/data/themedir1/block-theme-child-with-block-style-variations/styles/block-style-variation-a.json ❔ phpunit/data/themedir1/block-theme-child-with-block-style-variations/theme.json ❔ phpunit/data/themedir1/block-theme/styles/block-style-variation-a.json ❔ phpunit/data/themedir1/block-theme/styles/block-style-variation-b.json ❔ lib/class-wp-theme-json-gutenberg.php ❔ lib/class-wp-theme-json-resolver-gutenberg.php ❔ lib/load.php ❔ phpunit/class-wp-theme-json-resolver-test.php |
|
Size Change: -422 B (-0.02%) Total Size: 1.74 MB
ℹ️ View Unchanged
|
aaronrobertshaw
force-pushed
the
add/section-styling-via-block-styles
branch
2 times, most recently
from
e6ba6a7
to
79f5765
Compare
aaronrobertshaw
force-pushed
the
add/section-styling-via-block-styles
branch
2 times, most recently
from
08be716
to
fb14f6b
Compare
|
Testing this now: registering styles via PHP is working as expected but I can't get it to work by adding a "variations" section to TT4's under styles > blocks, not sure if that's right? |
|
Thanks for giving this a run @tellthemachines 👍
This is a known issue flagged by @richtabor a few days ago. The issue is there is no automatic registration of block style variations defined in a theme style variation. It currently relies on the block style variation being registered either by the primary theme (e.g. standalone partial theme.json file under /block-styles) or through the PHP I've been AFK recently but am just now picking this back up. So automatic registration of theme style variations should be implemented here soon. What might delay that though is we need to decide if theme style variation definitions of block style variations, should completely replace those defined by the theme or be merged as per about all other Global Styles. |
I'd lean towards merging to start. Reasoning is you might have variations that just change certain characteristics but not others e.g. you want dark background of parent variation but border radius of child. It's a little more flexible. |
Thanks for the quick feedback on that @SaxonF 🚀 The current approach in this PR is to merge any block style variation definitions. When a theme style variation is applied, its data is basically copied into the user's Global Styles. This includes the new There is a new filter that resolves these definitions under their respective block types within the user origin. That process honours any current tweaks a user has made to a block style variation for the current theme (including theme style variation). That side of it is working ok from recent testing. The one catch is how a theme style variation might opt out of a block style variation defined by the primary theme. We might be able to allow the theme style variations to set the block style variation it wants to opt out of to FWIW, the merging of variation styles is also in line with some other ongoing conversations around how settings should be merged across origins. Moving forward, I don't think beginning with a merge-based approach hurts us long term. Any early adopters who would have preferred the "replacement" approach can just define complete overrides for the block style variations within a theme style variation. By that I mean, any styles set on the original variation would have a matching one in the theme style variation version. If we then later moved to a complete replacement of block style variations with those in the theme style variation, those early definitions would only have a few extra styles defined that could potentially be removed. |
|
Flaky tests detected in a24faaf. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/9263075329
|
aaronrobertshaw
force-pushed
the
add/section-styling-via-block-styles
branch
from
48a9132
to
164586d
Compare
aaronrobertshaw
changed the base branch from
trunk
to
try/reduce-global-styles-specificity
|
I think this PR is getting closer to being ready to move out of draft status but there are a few aspects to it I'd like to flag and see if there are some better approaches.
Update: As flagged in #57908 (comment), the Maintaining style load order for editor overrides
With zero specificity styles, the load order is key to the cascade functioning correctly. Before this PR, This is complicated further by the need to be able to apply variations to blocks at different levels in the hierarchy, in different orders. Achieving the desired behaviour, required passing along data that indicated which applications of variations occurred within the inner blocks. This meant that if an existing variation was being changed in the editor, its style overrides could be updated but any overrides for inner variations would be kept/moved after the parent in the load order. While this would already be the case for an existing application of a variation, a new entry in the To be able to keep the variation IDs predictable and aligned with the generated stylesheet for the variation, it turned out the Merging The requirement to support block style variation definitions from within a theme style variation meant that the variation definitions would live at the @youknowriad and @ellatrix, if you can spare some time, it would be great to get your thoughts, suggestions, and wisdom on this PR 🙏 |
aaronrobertshaw
force-pushed
the
add/section-styling-via-block-styles
branch
from
a694f89
to
1c8b54b
Compare
|
Update here on my latest understanding of the issue - https://github.com/WordPress/wordpress-develop/pull/6271/files#r1619805687. I don't think the error is an immediate concern, as the core backport for sections styling resolves the issue. Most important thing is to get the backport committed. There's some conversation required around how Gutenberg will extend the theme json when implementing new features in the future though. |
|
Nice sleuthing @talldan 🕵️
Agreed. As far as this PR and feature are concerned, once the backport is merged, I think we're good. |
Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This is done by extending block style variations to apply to nested blocks. See WordPress/gutenberg#57908. Fixes #61312. Props aaronrobertshaw, talldanwp, ramonopoly, isabel_brison, andrewserong. git-svn-id: https://develop.svn.wordpress.org/trunk@58264 602fd350-edb4-49c9-b593-d223f7449a82
Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This is done by extending block style variations to apply to nested blocks. See WordPress/gutenberg#57908. Fixes #61312. Props aaronrobertshaw, talldanwp, ramonopoly, isabel_brison, andrewserong. Built from https://develop.svn.wordpress.org/trunk@58264 git-svn-id: http://core.svn.wordpress.org/trunk@57727 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This is done by extending block style variations to apply to nested blocks. See WordPress/gutenberg#57908. Fixes #61312. Props aaronrobertshaw, talldanwp, ramonopoly, isabel_brison, andrewserong. Built from https://develop.svn.wordpress.org/trunk@58264 git-svn-id: https://core.svn.wordpress.org/trunk@57727 1a063a9b-81f0-0310-95a4-ce76da25c4cd
…g section styling (WordPress#57908) Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org> Co-authored-by: tellthemachines <isabel_brison@git.wordpress.org> Co-authored-by: ramonjd <ramonopoly@git.wordpress.org> Co-authored-by: talldan <talldanwp@git.wordpress.org> Co-authored-by: youknowriad <youknowriad@git.wordpress.org> Co-authored-by: ellatrix <ellatrix@git.wordpress.org> Co-authored-by: SaxonF <saxonafletcher@git.wordpress.org> Co-authored-by: richtabor <richtabor@git.wordpress.org> Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org> Co-authored-by: cbirdsong <cbirdsong@git.wordpress.org> Co-authored-by: bacoords <bacoords@git.wordpress.org> Co-authored-by: getdave <get_dave@git.wordpress.org> Co-authored-by: colorful-tones <colorful-tones@git.wordpress.org> Co-authored-by: hanneslsm <hanneslsm@git.wordpress.org> Co-authored-by: andrewserong <andrewserong@git.wordpress.org> Co-authored-by: kevin940726 <kevin940726@git.wordpress.org> Co-authored-by: ajlende <ajlende@git.wordpress.org> Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org> Co-authored-by: scruffian <scruffian@git.wordpress.org>
Dev Note - Section Styles (draft)In WordPress 6.6, Section Styles simplify the process of styling individual sections of a webpage by offering users a one-click application of curated styles, eliminating the need for repetitive manual configuration. What's Changed?Section-based styling has been enabled by extending the existing Block Styles feature (aka block style variations) to support styling inner elements and blocks. These enhanced block style variations can even be applied in a nested fashion due to uniform CSS specificity ( In addition, block style variations can now be:
UsageRegistration of Block Style VariationsThe block style variations that can be defined and manipulated through Global Styles are limited to those that have been registered with the Any unregistered block style variation defined within a theme.json partial with be automatically registered. Outlined below are three approaches to registering extended block style variations. The approaches leveraging theme.json definitions will automatically register the block style variation with the Defining Block Style VariationsOutlined below are recommended approaches to registering extended block style variations. Theme.json Partial FilesWith the extension of block style variations to support inner element and block type styles, they essentially are their own theme.json file much like theme style variations. As such, block style variations also reside under a theme's A new {
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Variation A",
"slug": "variation-a",
"blockTypes": [ "core/group", "core/columns", "core/media-text" ],
"styles": {
"color": {
"background": "#eed8d3",
"text": "#201819"
},
"elements": {
"heading": {
"color": {
"text": "#201819"
}
}
},
"blocks": {
"core/group": {
"color": {
"background": "#825f58",
"text": "#eed8d3"
},
"elements": {
"heading": {
"color": {
"text": "#eed8d3"
}
}
}
}
}
}
}ProgrammaticallyWithin a theme's register_block_style(
array( 'core/group', 'core/columns' ),
array(
'name' => 'green',
'label' => __( 'Green' ),
'style_data' => array(
'color' => array(
'background' => '#4f6f52',
'text' => '#d2e3c8',
),
'blocks' => array(
'core/group' => array(
'color' => array(
'background' => '#739072',
'text' => '#e3eedd',
),
),
),
'elements' => array(
'link' => array(
'color' => array(
'text' => '#ead196',
),
':hover' => array(
'color' => array(
'text' => '#ebd9b4',
),
),
),
),
),
)
)Via Theme Style Variations (Not Recommended)This approach has been enabled as a temporary means to facilitate ergonomic definitions of shared block style variations through theme style variations. It is being flagged here for transparency however it will likely be deprecated soon as the Global Styles architecture is updated to address growing complexity and simplify its mental model. More details on what's ahead for Global Styles can be found in this issue. Shared block style variations can be defined via Additionally, a new translatable title property has been added here to mirror the capabilities of the theme.json partial files outlined above. The key for the variation correlates to the {
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Theme Style Variation",
"styles": {
"variations": {
"variation-a": {
"color": {
"background": "#eed8d3",
"text": "#201819"
},
"elements": {
"heading": {
"color": {
"text": "#201819"
}
},
},
"blocks": {
"core/group": {
"color": {
"background": "#825f58",
"text": "#eed8d3"
},
"elements": {
"heading": {
"color": {
"text": "#eed8d3"
}
}
}
}
}
},
}
}
}Backwards CompatibilityAs the Section Styles feature was implemented via extensions to block style variations rather than as a replacement, existing block style variations will continue to work as before. LimitationsThe following limitations for block style variations in WordPress 6.6 should be noted:
What's Next?The Global Styles UI for block style variations will be updated to facilitate the customization of all available styles for inner elements and block types. This includes potentially enhancing the Style Book to support block style variations. Another future enhancement is the possible support for settings per block style variations. Useful Links
|
aaronrobertshaw
added
has dev note
…g section styling (WordPress#57908) Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org> Co-authored-by: tellthemachines <isabel_brison@git.wordpress.org> Co-authored-by: ramonjd <ramonopoly@git.wordpress.org> Co-authored-by: talldan <talldanwp@git.wordpress.org> Co-authored-by: youknowriad <youknowriad@git.wordpress.org> Co-authored-by: ellatrix <ellatrix@git.wordpress.org> Co-authored-by: SaxonF <saxonafletcher@git.wordpress.org> Co-authored-by: richtabor <richtabor@git.wordpress.org> Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org> Co-authored-by: cbirdsong <cbirdsong@git.wordpress.org> Co-authored-by: bacoords <bacoords@git.wordpress.org> Co-authored-by: getdave <get_dave@git.wordpress.org> Co-authored-by: colorful-tones <colorful-tones@git.wordpress.org> Co-authored-by: hanneslsm <hanneslsm@git.wordpress.org> Co-authored-by: andrewserong <andrewserong@git.wordpress.org> Co-authored-by: kevin940726 <kevin940726@git.wordpress.org> Co-authored-by: ajlende <ajlende@git.wordpress.org> Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org> Co-authored-by: scruffian <scruffian@git.wordpress.org>
| getBlockTypes(), | ||
| getBlockStyles, | ||
| clientId | ||
| ); |
There was a problem hiding this comment.
What is this? Why are we getting all "block selectors" (not sure what this is but it seems more than just variation related stuff), and for all block types?
There was a problem hiding this comment.
From memory, we're getting all the block selectors as block style variations can define styles for inner blocks. Those blocks can define custom selectors for certain features. For example, border styles might be applied to an inner element like in the Image block for example.
So the variations styles need to also apply the inner block styles correctly using those same selectors retrieved normally.
There was a problem hiding this comment.
Could be only get the block types of the blocks as inner blocks?
There was a problem hiding this comment.
That might be an optimisation we can make. At the moment, I'm a little preoccupied with updates over in #62712
|
I've updated the dev note comment in to be in line with updates in #62712 that should be landing soon. I'll update the make post accordingly too. |
| function useBlockProps( { name, className, clientId } ) { | ||
| const { getBlockStyles } = useSelect( blocksStore ); | ||
|
|
||
| const registeredStyles = getBlockStyles( name ); |
There was a problem hiding this comment.
Calling a store selector during render could lead to some unexpected results.
The hook isn't subscribed to block style updates, and it will only fetch new values when the consumer or useBlockSyleVariation triggers a re-render.
There was a problem hiding this comment.
Would there be a risk when new styles are registered/deregistered?
I don't know yet if it's worth it, but I think by refactoring getBlockSelectors or creating a new function that accepts a single block type and registeredStyles (and not the function), it'd be possible to call getBlockStyles in the store subscription callback, e.g.,
const blockType = useMemo(
() =>
getBlockTypes().find(
( { name: blockName } ) => blockName === name
),
[ name ]
);
const { registeredStyles } = useSelect(
( select ) => {
const { getBlockStyles } = select( blocksStore );
return {
registeredStyles: getBlockStyles( name ),
};
},
[ name ]
);
...
const blockSelectors = getBlockSelectorForBlock(
blockType,
registeredStyles,
clientId
);
Addresses:
Related:
What?
#56540 aimed to render block style variation styles within the overall global styles stylesheet. This was problematic in that it required increasing specificity of element styles applied to block instances as well as being unable to be reliably nested.
The idea in this PR is to reduce the specificity as far as possible for block style variations and their inner element and block type styles. Then generate stylesheets for the application of these variations in the order of their application (parent > child > grandchild etc) such that the correct cascade is maintained. This is so block style variations can be applied on nested blocks.
Why?
The ability to style entire sections of a page without having to tediously reapply the same sets of styles is greatly desired. Block style variations seemed to be the best mechanism for defining these styles.
How?
blockTypesproperty.blockTypeskey, it will be treated as a theme style variation for backwards compatibility./stylesthat have"block"within its defined scopesstyles.blocks.variationsproperty of a theme's primary theme.json filestyles.blocks.variationsproperty of a theme style variation partial theme.jsonstyles.blocks.core/group.variationsblock-style-variationsblock support has been added that injects a unique CSS class per block instance application of a block style variation.useBlockPropsto generate the styles on the editor side so they update correctly upon application to blocks./stylesThis PR is a bit of a monster but would be much more difficult to test properly if split up. It will be easier to review the code changes per commit as they were deliberately made in smaller conceptual chunks.
Next Steps
There are two main follow-ups needed and both will be explored separately once this initial iteration has merged.
/stylesdirectoryTesting Instructions
Setting up test block style variations
There are several methods by which block style variations can be added.
gutenberg_register_block_style/stylessubdirectorystyles.blocks.variationsProgrammatically
Within a theme's functions.php or a plugin, a call can me made to the new extended version of
gutenberg_register_block_style, passing it an array of block types the variation can be used with as well as a style object definition the variation's styles. The theme.json resolver will absorb any styles registered via this approach into the theme's theme.json data.Example usage
Standalone partial files
These partials will live (for now) under the/block-stylesdirectory in the theme directory.Block style variation theme.json partial files share the same directory as theme style variations, i.e.
/stylesin the theme directory.These theme.json partial files will support a new
blockTypesproperty.The new
blockTypesproperty serves a dual purpose. Firstly, it defines an array of block types the variation is available for. Secondly, if it is a non-empty array, it flags a variation as a block style variation.These block style variations will be automatically registered and absorbed into the theme's theme.json data by the resolver.
Example
{ "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 2, "title": "Variation A", "blockTypes": [ "core/group", "core/columns", "core/media-text" ], "styles": { "color": { "background": "#eed8d3", "text": "#201819" }, "elements": { "heading": { "color": { "text": "#201819" } } }, "blocks": { "core/group": { "color": { "background": "#825f58", "text": "#eed8d3" }, "elements": { "heading": { "color": { "text": "#eed8d3" } } } } } } }Defined by theme style variations
As theme style variations are essentially theme.json partials themselves that are copied into the user origin's theme.json data, they can't easily pull into other partials for block style variations. This lead to reintroducing the
styles.blocks.variationsproperty for theme.json.Similar to the standalone block style variations, each definition under
styles.blocks.variationswill require a new propertyblockTypesto define the block types that get the variation.Example
{ "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 2, "title": "Red", "styles": { "blocks": { "variations": { "variation-a": { "blockTypes": [ "core/group", "core/columns" ], "color": { "background": "#eed8d3", "text": "#201819" }, "elements": { "heading": { "color": { "text": "#201819" } } }, "blocks": { "core/group": { "color": { "background": "#825f58", "text": "#eed8d3" }, "elements": { "heading": { "color": { "text": "#eed8d3" } } } } } } } } }Things to test
Testing Instructions for Keyboard
Screenshots or screencast
Screen.Recording.2024-05-28.at.6.36.06.PM.mp4
Quickly hacked together TT4 child theme used in above demo.