search

WordPress / gutenberg

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

Dev Notes Tracking Issue for WordPress 5.9 #36401

Closed Mamaduka closed 2 years ago

Mamaduka commented 3 years ago

For WordPress 5.9, a Github project is being used to track dev notes and their progress. You can find the dev notes project view here - https://github.com/orgs/WordPress/projects/11/views/8.

Please share your notes here as comments or links to shared documents. The dev notes should be posted before WP 5.9 RC (30 November).

Please leave a comment if you're unable to write a note for your PR.

mkaz commented 3 years ago

Thanks @Mamaduka for starting, I'm pinging the current assignees to notes below. The assignment is based on the merged PR. As George said above, if you're unable to write your Dev Note, let us know and we can help.

Also, several items listed might be covered in a single Dev Note, we can discuss here how to combine. Personally, I'd like to see fewer Dev Notes with more details in each, when possible. Something like a single Global Styles note. This makes it easier for extenders to find and get all the information they need.

Full Site Editing Dev Note

Can the following issues be grouped into a single Full Site Editing dev note?

torounit commented 2 years ago

Thanks ! @Mamaduka @mkaz

Where should I put my Dev Note? In the comments section of PR?

mkaz commented 2 years ago

Hi @torounit - yes, you can put it as a comment in the PR itself, or you can also add as a comment on this PR. I can help review and get it published when ready. Thank you!

fabiankaegy commented 2 years ago

@mkaz I drafted a Dev note for the useInnerBlockProps hook here in the ticket itself: https://github.com/WordPress/gutenberg/pull/26031#issuecomment-996785144

youknowriad commented 2 years ago

Here's a data module related dev note, if there are more data module dev notes, they could potentially be grouped together in a post.

Data Module

batch function

WordPress 5.9 introduces the batch function in the data module. It allows you to trigger multiple consecutive actions to one or several data stores without re-rendering the components or notifying any data store subscriber. The store listeners are only notified when the batch callback ends.

This can be useful for performance improvement in situations where it's unnecessary to try to rerender all the components while all the actions didn't trigger yet. As an example, when typing in the canvas, the block editor generally triggers two action on each character being typed: one action to update the content of the post and another one to track the current text selection. In order to avoid unnecessary re-renders which can impact the typing performance we batch these two actions together.

Example:

import { useRegistry } from '@wordpress/data';

function Component() {
  const registry = useRegistry();
  function callback() {
    // This will only rerender the components once. 
    registry.batch( () => { 
      registry.dispatch( someStore ).someAction(); 
      registry.dispatch( someStore ).someOtherAction(); 
    } );
  }

  return <button onClick={ callback }>Click me</button>;
}
youknowriad commented 2 years ago

@mkaz while not mentioned above but I think the most important dev note for 5.9 is going to be a dev note about block themes: how to write them, difference with existing theme, opt-in, link to docs, where to find them in the theme repo...

youknowriad commented 2 years ago

Here's a dev note about block gap, a block support and theme.json config. I believe there are more customization tools made stable in this release, folks like @andrewserong @aaroncampbell @oandregal would know more here and potentially complete this to do a "customization/theme.json dev note". I guess we should also mention the "appearanceTools" flag in this dev note.

Block Gap

WordPress 5.9 introduces a new customization tool that you can control through the theme.json config of your theme: Block Gap.

The blockGap adjusts the vertical margin, or gap, between blocks. It is also used for gap between inner blocks in rows, buttons, and social icons. In the editor, the control for the blockGap is called Block spacing, located in the Dimensions panel.

By default the block gap support is disabled for all themes, but you can enable it in your theme.json with two different ways:

Example (theme.json)

{
    "version": 1,
    "settings": {
        "spacing": {
            "blockGap": true,
        }
    },
    "styles": {
        "spacing": {
            "blockGap": "1.5rem"
        }
    }
}
jorgefilipecosta commented 2 years ago

Here is a dev note for PR https://github.com/WordPress/gutenberg/pull/35562.

Updates to property onChangeComplete on ColorPicker component

The property onChangeComplete was deprecated to make the component more consistent with the rest of the codebase. Developers should update their code to the onChange property, a function that receives just a string with the color code. The property onChangeComplete received an object instead of a string. We tried to be back-compatible, and in many cases, onChangeComplete could still be used (although not recommended). The following properties of the object passed to onChangeComplete are still valid hex, rgb, hsv, hsl, source, oldHue. The property color that contained a tinycolor2 color object is no longer valid. Code that relied on the color property must be updated as the property is not present anymore because we removed the tinycolor2 library from the project. This change should have almost no impact as the ColorPicker component is a very low-level component used to implement the picking of custom colors, this component, although useful internally, is not very useful to outside plugin developers. Therefore, code that uses the higher level and useful components like ColorPalette or PanelColorGradientSettingsdoes not require updates related to this change.

mkaz commented 2 years ago

Thanks @youknowriad and @jorgefilipecosta for the updates and notes!

The blockGap should be combined with other styles and theme updates.

As for data and components, both are short, should we combine into a misc updates for WP 5.9? This could also include the deprecations and a few other smaller ones above

youknowriad commented 2 years ago

Sounds like a good plan to me. I'll share my remaining one (removed APIs) later (tomorrow most likely) which should also go into the misc updates.

mkaz commented 2 years ago

@youknowriad I wrote up a draft dev note for block theme here. Let me know if that covers what you had in mind or if I'm missing anything. 👍

youknowriad commented 2 years ago

@mkaz That reads more as an introduction to block themes with links to dig deeper. I think that's one of the approaches we could take. It's fine by me, but I just want to make sure that it's ok for dev notes to be written that way.

Also, the other day I wanted to look at the theme documentation to submit a block theme and it's essentially tailored for classic themes, we'll have to make some updates there in the next weeks.

Also some things maybe worth mentioning in the dev note:

mkaz commented 2 years ago

We've been talking with the theme team and have a docs ticket open to update the Theme handbook. So that work is in progress.

It's hard to tackle how to create a block theme in a single dev note. I'll look at adding the theme.json and pattern block in the note too.

torounit commented 2 years ago

@mkaz I wrote a draft note about editor.PostTaxonomyType .

https://github.com/WordPress/gutenberg/pull/33418#issuecomment-1003661959

mkaz commented 2 years ago

Thanks @torounit, it looks good. I've added it to the Misecellany dev note that will be published shortly around the RC1.

oandregal commented 2 years ago

Add API to access global settings, styles, and stylesheet #34843 @oandregal

Public PHP API to access global settings & styles from theme.json

Following the introduction of a theme.json API in WordPress 5.8 and its corresponding JavaScript API, WordPress 5.9 comes with a PHP public API to read data from theme.json.

Access to settings & styles

The following new functions give access to the settings and styles keys found in a theme.json:

wp_get_global_settings( $path = array() , $context = array() );
wp_get_global_styles( $path = array(), $context = array() );

where:

Some examples:

// Returns all settings
// after merging defaults, theme, and user data.
wp_get_global_settings(); 

// Returns the blockGap setting
// after merging defaults, theme, and user data.
wp_get_global_settings( array( 'spacing', 'blockGap' ) );

// Returns the borderRadius style for the group block
// after merging default, theme, and user data.
wp_get_global_styles(
  array( 'border', 'radius' ),
  array( 'block_name' => 'core/group' )
); 

// Returns the background color for the block paragraph
// after merging defaults and theme data (ignoring user data).
wp_get_global_styles(
  array( 'color', 'background' ),
  array(
    'block_name' => 'core/paragraph',
    'origin'     => 'base',
  )
);

Access to the resulting stylesheet

Additionally, there's a function to generate the stylesheet resulting of merging defaults, theme, and custom settings and styles:

wp_get_global_stylesheet( $types = array() );

where $types is a list of the styles to generate. Valid values are:

This function also considers whether the theme has theme.json support or not, abstracting that implementation detail from the consumers. By default, all styles are returned if the theme supports theme.json; if it doesn't, only styles for variables and presets are returned.

Note that this function only takes care of generating the stylesheet string, it doesn't actually enqueue any styles.

mkaz commented 2 years ago

@oandregal Thanks for the note 👍 Published to: https://make.wordpress.org/core/2022/01/04/new-api-to-access-global-settings-styles/

The misc note is published here: https://make.wordpress.org/core/2022/01/04/miscellaneous-block-editor-changes-in-wordpress-5-9/

The block theme note is published here: https://make.wordpress.org/core/2022/01/04/block-themes-a-new-way-to-build-themes-in-wordpress-5-9/

mkaz commented 2 years ago

@oandregal @youknowriad I've created a draft for the Customization Tools for theme.json using the blockGap note above. Is there more you want to include? The draft is started here: https://make.wordpress.org/core/wp-admin/post.php?post=93196&action=edit

youknowriad commented 2 years ago

That looks good, I'm pretty sure there are more design tools added during this cycle, maybe borders? @aaronrobertshaw and @andrewserong would know more.

oandregal commented 2 years ago

@mkaz @youknowriad I can't access the draft shared by Marcus. I was thinking that we could create a devnote called "theme.json v2" that tracks all changes done from v1. This is what I have so far. Need to fill the later sections, it's my focus for today. I'll update this comment as I make progress.

Changes in v2 of theme.json

WordPress 5.9 is evolving the theme.json v1 introduced in WordPress 5.8 to a v2. The existing v1 theme.json files will still work as expected, and they'll be transformed at runtime to the v2 format by WordPress.

Please, refer to the live specification document for a detailed description of the theme.json file capabilities.

Changes per section

Version

It's now 2 instead of 1.

You don't need to update the v1 file for it to work, as it'll be transformed into v2 at runtime for you. However, if you want to update a v1 file, keep in mind that you have to update the version value and potentially change the names of some keys. See below for a full set of changes.

For example, one of the changes from v1 to v2 is that the customLineHeight key has been renamed to lineHeight. Besides changing version from 1 to 2 you also need to rename the old customLineHeight name, as it's an invalid key for v2 file and will be ignored.

Settings

The following section documents the changes done to settings in v2:

Styles

The following section documents the changes done to styles in v2:

Custom templates

The customTemplates field has been introduced in version 2. It allows themes to declare their custom templates that should be present in the templates folder.

For example, for a custom template named my-custom-template.html, the theme.json can declare what post types can use it and what's the title to show the user:

Example (theme.json):

{
  "version": 2,
  "customTemplates": [
    {
      "name": "my-custom-template",
      "title": "The template title",
      "postTypes": [
        "page",
        "post",
        "my-cpt"
      ]
    }
  ]
}

Template parts

The templateParts field has been introduced in version 2. It allows themes to list the template parts present in the parts folder.

For example, for a template part named my-template-part.html, the theme.json can declare the area term for the template part entity which is responsible for rendering the corresponding block variation (Header block, Footer block, etc.) in the editor. Defining this area term in the theme.json will allow the setting to persist across all uses of that template part entity, as opposed to a block attribute that would only affect one block. Defining area as a block attribute is not recommended as this is only used 'behind the scenes' to aid in bridging the gap between placeholder flows and entity creation.

Currently block variations exist for "header" and "footer" values of the area term, any other values and template parts not defined in the json will default to the general template part block. Variations will be denoted by specific icons within the editor's interface, will default to the corresponding semantic HTML element for the wrapper (this can also be overridden by the tagName attribute set on the template part block), and will contextualize the template part allowing more custom flows in future editor improvements.

Example (theme.json):

{
  "version": 2,
  "templateParts": [
    {
      "name": "my-template-part",
      "title": "Header",
      "area": "header"
    }
  ]
}

Appearance tools

The new setting appearanceTools serves to opt-in into a number of other settings that are disabled by default, serving themes to quickly enable every setting available.

In v2, it opts-in into the following settings that are false by default:

BlockGap

The blockGap adjusts the vertical margin, or gap, between blocks. It is also used for gap between inner blocks in rows, buttons, and social icons. In the editor, the control for the blockGap is called Block spacing, located in the Dimensions panel.

By default the block gap support is disabled for all themes, but you can enable it in your theme.json with two different ways:

Example (theme.json):

{
    "version": 2,
    "settings": {
        "spacing": {
            "blockGap": true,
        }
    },
    "styles": {
        "spacing": {
            "blockGap": "1.5rem"
        }
    }
}

Changes to the global stylesheet

Default font sizes, colors, and gradients

The CSS for some of the presets defined by WordPress (font sizes, colors, and gradients) was loaded twice for most themes: in the block-library stylesheet plus in the global stylesheet. Additionally, there were slight differences in the CSS in both places.

We've consolidated the CSS of presets into the global stylesheet, that is now loaded for all themes. Each preset value generates a single CSS Custom Property and a class, as in:

/* CSS Custom Properties for the preset values */
body {
  --wp--preset--<PRESET_TYPE>--<PRESET_SLUG>: <DEFAULT_VALUE>;
  --wp--preset--color--pale-pink: #f78da7;
  --wp--preset--font-size--large: 36px;
  /* etc. */
}

/* CSS classes for the preset values */
.has-<PRESET_SLUG>-<PRESET_TYPE> { ... }
.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; } 
.has-large-font-size { font-size: var(--wp--preset--font-size--large) !important; }

For themes to override the default values they can use the theme.json and provide the same slug. Themes that do not use a theme.json can still override the default values by enqueuing some CSS that sets the corresponding CSS Custom Property.

Example (sets a new value for the default large font size):

:root {
 --wp--preset--font-size--large: <NEW_VALUE>;
}

Specificity for link colors provided by the user

In v1, when a user selected a link color for a specific block we attached a class to that block in the form of .wp-element-<ID> and then enqueued the following style:

.wp-element-<ID> a { color: <USER_COLOR_VALUE> !important; }

While this preserved user preferences at all times, the specificity was too strong and conflicted with some blocks with legit uses of the a HTML element but that shouldn't be considered links. To address this issue we've removed the !important and updated the corresponding blocks to style its a elements with a specificity higher than the user link color, which now is:

.wp-element-<ID> a { color: <USER_COLOR_VALUE>; }

As a result of this change, it's now the block author and theme author's responsibility to make sure the user choices are respected at all times at that the link color provided by the user (specificity 011) is not overridden.

oandregal commented 2 years ago

I've finalized the devnote for theme.json v2 above, which includes the devnotes for https://github.com/WordPress/gutenberg/pull/34334 https://github.com/WordPress/gutenberg/pull/34334 and https://github.com/WordPress/gutenberg/pull/33812/

noisysocks commented 2 years ago

Checking in on the status of the unchecked items in https://github.com/WordPress/gutenberg/issues/36401#issuecomment-966463138.

Make global styles available to all themes #34334 @oandregal Fix for link color in containers #34689 @oandregal

These are in https://github.com/WordPress/gutenberg/issues/36401#issuecomment-1004799517. Thanks @oandregal! Let me know when you've stopped adding to it and I can proofread and publish.

[RNMobile] Upgrade to RN 0.64 #29118 @cameronvoell

Not sure actually why this needs a dev note. The mobile stuff is separate to what ends up in Core, no? @youknowriad @cameronvoell

Introduce Block type level lock control #32457 @senadir

@senadir: Could you please write a dev note for this by Friday? You can post it as a comment in this thread.

Remove some low impact APIs that were deprecated on WP 5.3 #34537 @youknowriad

@youknowriad: Could you please write a dev note for this by Friday? Maybe add it to https://make.wordpress.org/core/2022/01/04/miscellaneous-block-editor-changes-in-wordpress-5-9/?

Save Navigation Block data to a wp_navigation post type #35746 @talldan

@talldan: Could you please write a dev note for this by Friday? It would be good to include it as part of a general dev note about the Navigation block since 5.9 is the first release containing this block. You can post it as a comment in this thread.

noisysocks commented 2 years ago

Save Navigation Block data to a wp_navigation post type #35746 @talldan

@talldan: Could you please write a dev note for this by Friday? It would be good to include it as part of a general dev note about the Navigation block since 5.9 is the first release containing this block. You can post it as a comment in this thread.

Oops just realised @talldan is away. @getdave: Could you please handle this?

aaronrobertshaw commented 2 years ago

I also can't access the draft shared by Marcus, so am not 100% sure what's been covered already.

That looks good, I'm pretty sure there are more design tools added during this cycle, maybe borders? @aaronrobertshaw and @andrewserong would know more.

The border design tools as far as block supports go are still behind the __experimentalBorder flag. There is some ongoing work refining those controls after which I expect that to be stabilised.

That leaves the border styling via theme.json which I think André's note covers.

youknowriad commented 2 years ago

[RNMobile] Upgrade to RN 0.64 #29118 @cameronvoell

This one for me was more about the upgrade to React 17 and mentioning potential small breaking changes (linking to React's blog post)

@youknowriad: Could you please write a dev note for this by Friday? Maybe add it to https://make.wordpress.org/core/2022/01/04/miscellaneous-block-editor-changes-in-wordpress-5-9/?

Yep, I'll do that 👍

getdave commented 2 years ago

Navigation block dev note

Save Navigation Block data to a wp_navigation post type #35746 @talldan

@talldan: Could you please write a dev note for this by Friday? It would be good to include it as part of a general dev note about the Navigation block since 5.9 is the first release containing this block. You can post it as a comment in this thread.

Oops just realised @talldan is away. @getdave: Could you please handle this?

@noisysocks I've drafted the dev note for the entire Navigation block as suggested. I've used Google Docs just for the collaborative editing aspect because the post is (currently) quite long. Now seeking feedback on what to add/remove - cc @adamziel @draganescu @talldan @mkaz @javierarce @jasmussen.

senadir commented 2 years ago

Block locking dev note

To facilitate creating better patterns and templates, WordPress 5.9 comes with a block level locking mechanism that works alongside templateLock. Instead of applying a lock to all inner blocks, you can apply it selectively to individual blocks via the lock attribute. The block level locking would supersede the inherited templateLock value. You can choose to lock moving or removing a block.

API definition

You can lock a block by default if you add locking to its definition

"attributes": {
    "lock": {
        "type": "object",
        "default": {
            "move": true,
            "remove": true, 
        },
    },
},

You can also lock a specific block in a pattern. In this example, the heading block is now locked and can't be removed:

<!-- wp:media-text {"align":"full","mediaType":"image","verticalAlignment":"center"} -->
<div class="wp-block-media-text alignfull is-stacked-on-mobile is-vertically-aligned-center">
    <figure class="wp-block-media-text__media"><img src="https://s.w.org/images/core/5.8/architecture-04.jpg" alt="Close-up, abstract view of architecture." /></figure>
    <div class="wp-block-media-text__content">
        <!-- wp:heading {"textAlign":"center","level":3,"style":{"color":{"text":"#000000"}},"lock":{"remove": true}} -->
        <h3 class="has-text-align-center has-text-color" id="open-spaces-1" style="color: #000000;"><strong>Open Spaces</strong></h3>
        <!-- /wp:heading -->

        <!-- wp:paragraph {"align":"center","fontSize":"extra-small"} -->
        <p class="has-text-align-center has-extra-small-font-size"><a href="#">See case study ↗</a></p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:media-text -->

Working alongside templateLock

Block locking supersedes template locking, so it can override it or undo it on the specified block:

For removing: lock.remove\templateLock "all" "insert" false
true can't Remove can't Remove can't Remove
false can Remove can Remove can Remove
undefined can't Remove can't Remove can Remove
For moving: lock.move\templateLock "all" "insert" false
true can't Move can't Move can't Move
false can Move can Move can Move
undefined can't Move can Move can Move

Unlike templateLock, block locking is not inheritable. If a block is locked from being removed, its children can still be removed. If you want to apply locking on children as well, add templateLock to the inner block component, or templateLock attribute to supporting blocks.

getdave commented 2 years ago

Nice work. A quick skim from me...

You can lock a block by default if add locking to its definition

by adding locking to its definition

Instead of applying a lock to all inner blocks, you can apply it selectively to individual blocks, via the lock attribute.

Suggest removing the last comma , as it's not required.

You can also lock a specific block in a pattern, in this example, the heading block is now locked and can't be removed:

I'd recommend you make this two separate sentences.

ad templateLock to the inner block component...

Amend to "add" (not "ad").

oandregal commented 2 years ago

These are in #36401 (comment). Thanks @oandregal! Let me know when you've stopped adding to it and I can proofread and publish.

@noisysocks I no longer plan to update anything.

youknowriad commented 2 years ago

@youknowriad: Could you please write a dev note for this by Friday? Maybe add it to https://make.wordpress.org/core/2022/01/04/miscellaneous-block-editor-changes-in-wordpress-5-9/?

Done ✅

mkaz commented 2 years ago

Thanks @senadir and @getdave - I published block locking dev note here ✅
https://make.wordpress.org/core/2022/01/08/locking-blocks-in-wordpress-5-9/

mkaz commented 2 years ago

@oandregal @noisysocks - I published out the theme.json dev note ✅ https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/

And that closes out this tracking issue. 🎉 thanks everyone !! 👏

noisysocks commented 2 years ago

Thanks for wrangling @mkaz ❤️ 🎉

ellatrix commented 2 years ago

Did we create a note for removing the post title alignment wrapper? I see it's ticked off but I don't see any note or discussion about it. Not sure if it's important to even mention. The note itself would be pretty short.

fabiankaegy commented 2 years ago

@ellatrix If I'm not mistaken it has been posted with some other items in this note here: Miscellaneous block editor changes in WordPress 5.9 :)

ellatrix commented 2 years ago

Ah, perfect! Thanks!