search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.58k stars 4.23k forks source link

6.1 Dev Notes Tracking #42961

Closed bph closed 2 years ago

bph commented 2 years ago

Tracking all Dev Notes from Gutenberg plugin releases 13.1 - 14.1

After a review of the processes establish during 6.0 release cycle, the release leads for documentation agreed on some modifications. Please read the information below carefully. If you have questions, connect with @bph or @zzap via Slack or comment here.

Not all developer related information needs to be in a separate DevNote on the Make Core blog for the field guide. We can group related information. During the course of the next few weeks, this first list will be completed after the last Gutenberg plugin. We can already make decision on some features if warrant a stand-alone blog post or if the information will be part of a group post.

Stand-alone post

To streamline the process and eliminate bottlenecks, all writers of stand-alone dev notes will receive privileges on the Make Core Blog. (Please connect with @bph or @zzap, if you need access)

Part of a group post

If the information related to your PR will be part of a group post, please write the dev note in a comment on the PR, so it can be reviewed and, if necessary commented on, by the release docs team or a reviewer.

Before you start writing

Global Styles

Layout

Elements support @scruffian

Fluid typography @ramonjd

Create Block Scaffolding Tool @gziolo / @ryanwelcher

Style Engine @ramonjd @andrewserong

Block Library (Package)

Query Loop @ntsekouras

Components package

Popover @ciampo (dev note here)

New APIs

useDisabled hook + disabled component

Deprecated

Unsorted for now

theme.json

Preference Persistence

Update 10/8 removed - #42485 not in 6.1

Updates: 10/03 - bph several more PR references

Updates: 9/21 / - bph

to be continued

ramonjd commented 2 years ago

Fluid typography @ramonjd

Thanks @bph! I have a dev note ready to roll, but have shelved it until we're closer to RC1. I am told this is the usual protocol.

bph commented 2 years ago

@ramonjd and all

Publishing close to RC 1 is not a hard rule. It only makes sure that there isn't something in the dev notes, the might have changed between drafting it and release.

On the doc release team we need a bit of a lead time as Dev Notes need to be reviewed by two people before publishing. If all dev notes are published a day before RC 1, it creates an unnecessary bottleneck and undue stress on the team.

Ideally, the draft on the make blog could be available around Beta 1. Then it can get into the queue for reviewers, finalized and published by RC 1, to make it into the Field Guide.

andrewserong commented 2 years ago

Thanks for the ping @bph!

For this one, I don't believe a separate post is required, it can be added to any dev note blog post on smaller changes. I've drafted a comment on the PR for inclusion in such a post: https://github.com/WordPress/gutenberg/pull/42544#issuecomment-1198863716 — the main purpose of the dev note is to communicate to creators of themes that currently use an undocumented approach of opting out of Layout styles to use the new formal approach.

bph commented 2 years ago

Thank you, @andrewserong - I marked this dev note as done for now.

bph commented 2 years ago

Thanks @ramonjd for message about the Draft Dev Note ready for review 👏  🙌

glendaviesnz commented 2 years ago

Draft for spacing presets available for review at https://make.wordpress.org/core/?p=98177&preview=1&_ppp=00c8d7730a

t-hamano commented 2 years ago

I commented on the above PR because I thought it should be mentioned in the dev note. In my opinion, it is better to include it as part of the group post, such as Block Editor miscellaneous Dev Notes for WordPress 6.0.

bph commented 2 years ago

Thank you so much @t-hamano to add this here and put this on our radar for WP 6.1.

scruffian commented 2 years ago

@bph I created a draft for elements support: https://make.wordpress.org/core/?p=98557

t-hamano commented 2 years ago

https://github.com/WordPress/gutenberg/pull/42677#issuecomment-1240126502 I have left a comment about "the inheritance of template lock in the column block", as it was deemed necessary to include this as part of the dev note.

bph commented 2 years ago

@scruffian Thanks for the Dev Note! and the link!

oandregal commented 2 years ago

I've listed the authors of #43840 in the issue description. I was listed but I was involved.

ntsekouras commented 2 years ago

👋 - I was wondering if all the additions in the templates offered to create in site editor should be part of post like this already posted one: https://make.wordpress.org/core/2022/07/21/core-editor-improvement-deeper-customization-with-more-template-options/.

Related PRs that Needs Dev Note label was added are:

For Query Loop extensibility PRs, there is going to be a documentation page(related open PR), so I guess that would be enough? 🤔

Finally for the Query Loop parents filter is just a filter for the block to restrict the results based on their parent. I don't think it needs a separate dev note, but if we want we could add somewhere a sentence about it like:

Query Loop has now parent filtering support, with a new property in the existing query attribute, called parents. The filter is only shown for hierarchical post types and if you have selected multiple parents it will display the children of all of them(union).

gziolo commented 2 years ago

I started a draft post for Block API changes covering:

For the Create Block section, there is also an open PR that we should land closer to the release date that integrates the new render API from block.json and bumps the minimum required WordPress version to 6.1:

Besides, we should mostly cover new CLI options / prompts that allow selecting different variants (dynamic vs static) and a way to scaffold code only for a block (without the plugin wrapper).

adamziel commented 2 years ago

@bph I've marked this one as done:

https://github.com/WordPress/gutenberg/pull/41873

It was closed without merging as there wasn't enough alignment to move forward.

andrewserong commented 2 years ago

I've added a draft note for the layout refactor in this comment (https://github.com/WordPress/gutenberg/pull/40875#issuecomment-1253190670). The layout dev notes will likely all be consolidated with ones from @tellthemachines and @ramonjd into a single blog post, since lots of the individual PRs and changes are all related.

tellthemachines commented 2 years ago

Oh, I think we need to add #42763 (Try "constrained" content width as new layout type) and #42085 (Core CSS support for root padding and alignfull blocks) to this list. I'm writing dev notes for them, anyway 😅

bph commented 2 years ago

@tellthemachines I updated the tracking section above.

getdave commented 2 years ago

I added a dev note for pseudo class support for elements in theme.json. It's being tech reviewed by @scruffian and @draganescu.

afragen commented 2 years ago

Block Library: Add filter for inner blocks in the Navigation block

I added a short dev note for this.

https://make.wordpress.org/core/?p=98980&preview=1&_ppp=56c57f986f

tellthemachines commented 2 years ago

Hey folks, there's a draft post for all Layout-related dev notes here: https://make.wordpress.org/core/?p=99019&preview=1&_ppp=992173a9ba

ramonjd commented 2 years ago

I've thrown up a first draft for the Style Engine dev note here:

https://make.wordpress.org/core/?p=99063&preview=1&_ppp=10ef94cb0b

Thank you!

fabiankaegy commented 2 years ago

I moved the draft of the block-based template parts devnote from the Google Doc to a draft post: https://make.wordpress.org/core/?p=99068&preview=1&_ppp=25529485e7

draganescu commented 2 years ago

Howdy here is the draft dev note for the navigation block fallback updates in 6.1 https://make.wordpress.org/core/?p=99073&preview=1&_ppp=82bfc16fed

oandregal commented 2 years ago

Closing the loop for https://github.com/WordPress/gutenberg/pull/44015 and https://github.com/WordPress/gutenberg/pull/44159

Draft at https://make.wordpress.org/core/?p=99398&preview=1&_ppp=40c8cd7718

Filters for theme.json

WordPress 6.1 has introduced some server-side filters to hook into the theme.json data provided at the different data layers:

Each filter receives an instance of the WP_Theme_JSON_Data class with the data for the respective layer. To provide new data, the filter callback needs to use the update_with( $new_data ) method, where $new_data is a valid theme.json-like structure. As with any theme.json, the new data needs to declare which version of the theme.json is using, so it can correctly be migrated to the runtime one, should it be different.

Example:

This is how to pass a new color palette for the theme and disable the text color UI:

function filter_theme_json_theme( $theme_json ){
    $new_data = array(
        'version'  => 2,
        'settings' => array(
            'color' => array(
                'text'       => false,
                'palette'    => array( /* New palette */
                    array(
                        'slug'  => 'foreground',
                        'color' => 'black',
                        'name'  => __( 'Foreground', 'theme-domain' ),
                    ),
                    array(
                        'slug'  => 'background',
                        'color' => 'white',
                        'name'  => __( 'Background', 'theme-domain' ),
                    ),
                ),
            ),
        ),
    );

    return $theme_json->update_with( $new_data );
}
add_filter( 'theme_json_theme', 'filter_theme_json_theme' );
oandregal commented 2 years ago

I've noticed that in the 6.1 cycle there has been a few features introduced in theme.json. Some I've tracked (there may be more):

I suggest that we create a "theme.json in WordPress 6.1" devnote to compile them all (whether or not some of those individual features merit its own devnote as well).

cc people that led the changes in this area in case anyone wants to draft it up. @scruffian @MaggieCabrera @mikachan @ajlende @getdave @draganescu @glendaviesnz @andrewserong @ramonjd @aaronrobertshaw

getdave commented 2 years ago

hover/focus/active states

Here's the Dev Note for this.

bph commented 2 years ago

@oandregal looking at your list in your comment

This is the current list of stand-alone Dev Notes already drafted on the Make Blog:

This is the list of theme.json PRs. See link list above. Screen Shot 2022-10-04 at 18 35 41 My idea would be to add "More Theme.json Updates" Dev Note covering the list and link to already existing Dev notes.

bph commented 2 years ago

@jorgefilipecosta @t-hamano We already have a "Block Library Updates" (public preview) Dev note in the works, where we can add a paragraph about these PRs

42677

43663

And if you can, also for #40554

What do you think? You can add it all in a comment on this issue together.

ryanwelcher commented 2 years ago

@bph combined dev note for the create-block stuff.

Create-Block Dev notes WP 6.1

WordPress 6.1 introduces many updates and new features to the @wordpress/create-block.

New Features

Block Variants

The new –variant flag allows users of the tool to choose a block variant to be scaffolded. The internal templates provided by the create-block package support a dynamic and static variant with will scaffold a dynamic and static block respectively. If no variant is passed, the static variant is used.

Scaffolding using the dynamic variant:

npx @wordpress/create-block custom-block --variant=dynamic

Template authors can define variants by adding a variants object to the template definition with each property being the name of a variant and its value an object containing values that can add to or overwrite the default values defined in the defaultValues key. See the create-block-tutorial-template for an example of defining variants.

Related pull requests:

–no-plugin mode

A highly requested feature for the package was to be able to add additional blocks to an existing plugin. With the addition of the --no-plugin flag that is now possible!

When the command is run with the flag, a new set of block files will be created in the directory where the command was run in a directory named for the slug passed.

npx @wordpress/create-block custom-block --no-plugin

Related pull requests: #41642

Enhancements:

Documentation

The documentation around creating External Templates has been split into its own section ( #43718) and links to the documentation in the associated create-block-tutorial-template have been fixed to link to the correct places ( #42839 ).

@bph Make draft if here: https://make.wordpress.org/core/?p=99350&preview=1&_ppp=79a1db742d

ntsekouras commented 2 years ago

Extending the Query Loop block

Extenders needed a way to present bespoke versions of the Query Loop block, with their own presets, additional settings and without customization options which are irrelevant to their use-case. With WordPress 6.1 the Query Loop block offers very powerful ways to create such versions, through block variations.

To make Wordpress recognize your variation you need to set the isActive block variation property. For providing an easy and consistent way for extenders to recognize and scope their own variation a new namespace property has been introduced in Query Loop block.

Query Loop block now supports controlling which filters are displayed in the user through the allowedControls property, making it easier to be configured by users.

Now you have control over the query executed to fetch the desired posts. You can change the query executed in the block editor by setting extra arguments to the query attribute of the block, and you can do the same for the front end by using the query_loop_block_query_vars filter.

Customizing Query Block Layout

To customize your variation's layout you can use the innerBlocks attribute to set the blocks that are available at the start, bypassing the set-up stage. You can also create specific Query Loop variation patterns to be suggested in the setup, and replace flows of the block. To connect a pattern to a Query Loop variation, add the name of your variation prefixed with the Query Loop name (e.g. core/query/$variation_name) to the pattern’s blockTypes property.

An example block variation would look like this:

const MY_VARIATION_NAME = 'my-plugin/books-list';

registerBlockVariation( 'core/query', {
    name: MY_VARIATION_NAME,
    title: 'Books List',
    description: 'Displays a list of books',
    isActive: [ 'namespace' ],
    icon: /** An SVG icon can go here*/,
    attributes: {
        namespace: MY_VARIATION_NAME,
        query: {
            perPage: 6,
            pages: 0,
            offset: 0,
            postType: 'book',
            order: 'desc',
            orderBy: 'date',
            author: '',
            search: '',
            exclude: [],
            sticky: '',
            inherit: false,
        },
    },
    allowedControls: [ 'inherit', 'order', 'taxQuery', 'search' ],
    scope: [ 'inserter' ],
);

There is a new documentation page specifically for extending Query Loop block to learn more.

props @sunyatasattva for the documentation page.

make.wordpress draft: https://make.wordpress.org/core/?p=99476&preview=1&_ppp=c35ff058a0

oandregal commented 2 years ago

@bph I've looked into changes and don't see anything left. People that worked actively in this area may want to double-check, cc @scruffian @ajlende @MaggieCabrera etc.

t-hamano commented 2 years ago

@bph

I will leave a note which should be added in the Block Libraries update in WordPress 6.1 post.

This note refers to three PRs:

If there are any misleading or unnatural phrases, please feel free to update them.

Navigation Block Menu Items filter

Content has already been created by @afragen.

Improvement of Cover Block

Markup changes

The markup has been changed to resolve the issue that duotone doesn't work with fixed background. Previously, the background image was applied to the root of the block, but it is now applied to the inner div with the img role and .wp-block-cover__image-background class.

Current:

<div class="wp-duotone-xxxxxx-xxxxxx-x wp-block-cover has-parallax" style="background-image:url(http://example.com/wp-content/uploads/2022/10/cover.jpg)">
    <span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
    <div class="wp-block-cover__inner-container">
        <p>Inner Contents</pss=>
    </div>
</div>

New:

<div class="wp-duotone-xxxxxx-xxxxxx-x wp-block-cover has-parallax">
    <span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
    <div role="img" class="wp-block-cover__image-background wp-image-xx has-parallax" style="background-image:url(http://example.com/wp-content/uploads/2022/09/cover.jpg)"></div>
    <div class="wp-block-cover__inner-container">
        <p>Inner Contents</p>
    </div>
</div>

For more info see #40554.

Keep the same position for both LTR and RTL languages

In the cover block, the content inside can be changed the content position, such as "Top Left" or "Center Right". But when changed to RTL languages, the content position flips left to right as compared to the LTR language. However, content position determines "physical" placement and should not be affected by language direction.

To solve this problem, the same position is now kept for both LTR and RTL languages. Because of this change, the content within the existing cover block in RTL languages is flipped left to right (i.e., in its original position), but if this is not what you are looking for, you can re-position it.

For more info see #43663.

Global template_lock inheritance in the column block

The block template defines a default list of blocks in an editor session. To prevent manipulation of the block list, all blocks can be locked by template_lock property.

However, in column blocks, the editor would crash on certain operations because it would initialize the lock status defined in the block template. To resolve this issue and to be more consistent about template lock status inheritance, column blocks now inherit the lock status of block templates.

For more info see #42677.

bph commented 2 years ago

Awesome, Thank you @t-hamano !

zzap commented 2 years ago

Just to let everyone know, I've been going through the drafts at Core blog and adding 6.1 label to a bunch of dev notes. That is the most important label for the release so please use it if.

Thank you for awesome work :heart:

bph commented 2 years ago

I have been doing that, to and I added dev-note-6.1 so we can collectively just refer to them in one tag. :-)

zzap commented 2 years ago

Yeah, but 6.1 + dev-notes are the ones that end up in here https://make.wordpress.org/core/6-1/

bph commented 2 years ago

Update: October 8th, 2022

Yesterday, 4 dev notes were published, six are finished and in the queue to be reviewed, one is still in progress.

Published 📣

In Review 👓

In Progress 📝

Block API changes in WordPress 6.1

Not claimed PRs

In the list in the issue description above we still have a few white check boxes next to PRs.

ramonjd commented 2 years ago

@bph Could we possibly hold off on publishing the fluid typography dev note for a few days? There are some bugs we're scrambling to iron out and it will affect the content of the dev note, which I will update in due course. See:

🙇

talldan commented 2 years ago

Persisted preferences - https://make.wordpress.org/core/wp-admin/post.php?post=99657&action=edit

Writing this did make me realise there's a bug in 6.1 RC related to the backport for persisted preferences, so I'll work on fixing that asap. 🤦‍♂️

oandregal commented 2 years ago

Oh, I forgot commenting about the settings hook. This is something client-specific and unrelated to server-side filters. It's about having a theme.json per block instance. Not all pieces to make this work have landed in 6.1, so I'm leaning towards not publishing the devnote just for now. cc @jorgefilipecosta in case he has thoughts.

jorgefilipecosta commented 2 years ago

Oh, I forgot commenting about the settings hook. This is something client-specific and unrelated to server-side filters. It's about having a theme.json per block instance. Not all pieces to make this work have landed in 6.1, so I'm leaning towards not publishing the devnote just for now. cc @jorgefilipecosta in case he has thoughts.

Yes, I agree it is something experimental that we will continue trying on the plugin. The dev note should not go out for now.

tyxla commented 2 years ago

@bph I've added a dev note for #44494 as a comment in the PR: https://github.com/WordPress/gutenberg/pull/44494#issuecomment-1273216585.

Mamaduka commented 2 years ago

I've added two dev notes for Block Editor misc post - https://github.com/WordPress/gutenberg/pull/40502#issuecomment-1273013749 and https://github.com/WordPress/gutenberg/pull/42186#issuecomment-1273020725.

bph commented 2 years ago

Thank You @tyxla and @Mamaduka for your notes! 😸

jorgefilipecosta commented 2 years ago

Here I add the missing dev note for https://github.com/WordPress/gutenberg/pull/41791. It can be included on a misc editor dev note.

Start content patterns for all post types.

With WordPress 6.0, we introduced the ability to add patterns that appear in a modal each time a new page was created, allowing the user to start from a set of pre-made patterns instead of in a blank state. In WordPress 6.1, this feature is expanded to all the post types. To use this feature, one should include 'core/post-content' in the blockTypes array (same as what happened for pages) and include the desired postTypes where the modal should appear in a newly introduced postTypes property. If postTypes are specified, the pattern is only available on the post types that were set. Example:

register_block_pattern( 'custom-pattern', array(
            'title'      => _x( 'Start post pattern', 'Block pattern title', 'gutenberg' ),
            'blockTypes' => array( 'core/paragraph', 'core/post-content' ),
            'postTypes' => array( 'product' ),
            'content'    => '<!-- wp:paragraph -->
<p>A start post pattern</p>
<!-- /wp:paragraph -->',
        ) );
bph commented 2 years ago

20 post published

This is definitely more than 5.9 (9) and 6.0 (9) together. :-) 🙌 🤯

👏 props to @scruffian @glendaviesnz @ramonjd @oandregal @draganescu @jorgefilipecosta @tellthemachines @scruffian @getdave @andrewserong @fabiankaegy @Mamaduka @annezazu @afragen @t-hamano @ellatrix @adamziel @gziolo @ciampo @mirka @aaronrobertshaw @talldan @ramonjd @ntsekouras @ryanwelcher @mburridge and Abha Thakor.

I close this issue, but if you find PRs that still need to have a mention in the Field Guide 6.1 by all means comment below and ping me.

r-interactive commented 6 months ago

Extending the Query Loop block

Extenders needed a way to present bespoke versions of the Query Loop block, with their own presets, additional settings and without customization options which are irrelevant to their use-case. With WordPress 6.1 the Query Loop block offers very powerful ways to create such versions, through block variations.

To make Wordpress recognize your variation you need to set the isActive block variation property. For providing an easy and consistent way for extenders to recognize and scope their own variation a new namespace property has been introduced in Query Loop block.

Query Loop block now supports controlling which filters are displayed in the user through the allowedControls property, making it easier to be configured by users.

Now you have control over the query executed to fetch the desired posts. You can change the query executed in the block editor by setting extra arguments to the query attribute of the block, and you can do the same for the front end by using the query_loop_block_query_vars filter.

Customizing Query Block Layout

To customize your variation's layout you can use the innerBlocks attribute to set the blocks that are available at the start, bypassing the set-up stage. You can also create specific Query Loop variation patterns to be suggested in the setup, and replace flows of the block. To connect a pattern to a Query Loop variation, add the name of your variation prefixed with the Query Loop name (e.g. core/query/$variation_name) to the pattern’s blockTypes property.

An example block variation would look like this:

const MY_VARIATION_NAME = 'my-plugin/books-list';

registerBlockVariation( 'core/query', {
    name: MY_VARIATION_NAME,
    title: 'Books List',
    description: 'Displays a list of books',
    isActive: [ 'namespace' ],
    icon: /** An SVG icon can go here*/,
    attributes: {
        namespace: MY_VARIATION_NAME,
        query: {
            perPage: 6,
            pages: 0,
            offset: 0,
            postType: 'book',
            order: 'desc',
            orderBy: 'date',
            author: '',
            search: '',
            exclude: [],
            sticky: '',
            inherit: false,
        },
    },
    allowedControls: [ 'inherit', 'order', 'taxQuery', 'search' ],
    scope: [ 'inserter' ],
);

There is a new documentation page specifically for extending Query Loop block to learn more.

props @sunyatasattva for the documentation page.

make.wordpress draft: https://make.wordpress.org/core/?p=99476&preview=1&_ppp=c35ff058a0

I have questions about ‘connecting’ a pattern with a Query Loop variation, mentioned in the section “Customize your variation layout”:

_“In order for a pattern to be “connected” with a Query Loop variation, you should add the name of your variation prefixed with the Query Loop name (e.g. core/query/$variationname) to the pattern’s blockTypes property. For more details about registering patterns see here.”

I don’t quite understand, and it’s not working for me. It will be great if there’s a simple example on how to connect a pattern with a query loop variation.

I do have the variation created in the js file, using registerBlockVariation(), similar to the examples that you have above. My variation name is 'my-test-variation'

const MY_VARIATION_NAME = 'my-test-variation';

registerBlockVariation(
  'core/query',
  {
    name: MY_VARIATION_NAME,
    title: 'Books List',
    description: 'Displays a list of books',
    isActive: [ 'namespace' ],
    icon: 'book-alt',
    attributes: {
        namespace: MY_VARIATION_NAME,
        query: {
            perPage: 6,
            pages: 0,
            offset: 0,
            postType: 'book',
            order: 'desc',
            orderBy: 'date',
            author: '',
            search: '',
            exclude: [],
            sticky: '',
            inherit: false,
        },
    },
    allowedControls: [ 'inherit', 'order', 'taxQuery', 'search' ],
    scope: [ 'inserter','block' ],
  }
);

I have registered a pattern using register_block_pattern() in my functions.php, like below:

register_block_pattern(
    'test/posts-1-col',
    array(
        'title'      => __( 'My Test Pattern', 'my-plugin' ),
        'blockTypes' => array( 'core/query/my-test-variation' ),
        'content'    => '<!-- wp:query {"query":{"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true},"layout":{"type":"default"}} -->
<div class="wp-block-query">
  <!-- wp:post-template -->

  <!-- wp:group {"tagName":"article","style":{"spacing":{"padding":{"top":"var:preset|spacing|small","bottom":"var:preset|spacing|small"},"blockGap":"1.5rem"}},"layout":{"type":"default"}} -->
  <article class="wp-block-group" style="padding-top:var(--wp--preset--spacing--small);padding-bottom:var(--wp--preset--spacing--small)">
    <!-- wp:post-title {"isLink":true} /-->
    <!-- wp:post-excerpt /-->
  </article>
  <!-- /wp:group -->
  <!-- /wp:post-template -->

  <!-- wp:query-pagination {"paginationArrow":"arrow","layout":{"type":"flex","justifyContent":"center"}} -->
    <!-- wp:query-pagination-numbers /-->
  <!-- /wp:query-pagination -->

  <!-- wp:query-no-results -->
    <!-- wp:pattern {"slug":"spruce/hidden-no-results"} /-->
  <!-- /wp:query-no-results -->
</div>
<!-- /wp:query -->',
    )
);

What am I missing?

Thank you!