6.7 Dev Note Tracking Issue

[fabiankaegy]

Tracking all Dev Notes from Gutenberg plugin releases 18.6 - v19.3

Please read the information below carefully. If you have questions or suggestions, connect with @fabiankaegy via Slack, ping @fabiankaegy on GitHub, or comment here.

Important

🗓 Deadline Drafts for All Dev Notes - October 13th, 2024 (a few days before Beta 3, so there's enough time for reviews)
🗓 Deadline All Dev Notes Published - October 20nd, 2024 (a few days before RC1)

Not all developer-related information must be in a separate DevNote on the Make Core blog for the field guide. We can group related information. We can already decide whether some features warrant a stand-alone blog post or a group post.

Stand-alone post

To streamline the process and eliminate bottlenecks, all writers of stand-alone dev notes will write the dev notes on the Make Core Blog.

Instructions

• Create your note in a new post,
• Save as Draft
• Enable public preview
• Share the link to the public preview in a comment below as "ready for review"
• "For dev notes, each one must have at least two reviewers" (Handbook)

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 📣 please read the handbook pages:

• ⭐️ Writing developer notes
• ⭐️ Style & Substance section of the Post & Comment Guidelines for Make Blog
• ⭐️ Documentation Style Guide - Good for reference, when in doubt, especially when English is not your native language.

---

Note

The list is incomplete. We are in the process of reviewing plugin release changelogs and add them as we progress on the task.

There are two labels relevant to DevNotes :

• needs dev note
• has dev note

If you worked on a feature/module/component that definitely needs a dev note, please assign the label needs dev note If you already added the Dev Note to the make blog on draft or as a comment on the PR, please label it has dev note

---

TO DO

Progress of the Documentation work for WP 6.7 release (including the DevNotes tracked on this issue) can also be followed at WP 6.7 Documentation project dashboard

PRs with label has-dev-note or a related DevNote draft are marked with [x]

Standalone Posts:

• Editor: Add extensibility to PreviewOptions v2 #64644 - @lezama
• Split content view with open metaboxes #64351 - @stokesman
• Add plugin template registration API #61577 - @Aljullu [Draft]

Stabilize Role Attribute Property ✅ - [Draft]
@youknowriad and @getdave have agreed to work on this one and already shared a Draft.

• Blocks: Stabilise role attribute property #65484 - @getdave
• Block API: Introduce "local" attributes and use it for the image block #63076 - @youknowriad

Zoomed Out Mode
I'd love to have one dev note dedicated to all things Zoomed out mode that explains the feature and how to work with it. Including how stuff like the "Section detection algorithm" work.

@getdave has volunteered to help triage this :) A draft is available at #64197 (comment)

• Decouple "zoom/scaling the canvas" from zoom out mode (without mode rename) #65482
• Zoom out: remove experimental flag #65404
• Zoom out: Try vertical displacement when dragging a pattern between existing patterns/sections #63896
• Zoom Out: Only show the inserters when a block is selected or hovered #63668

Block Bindings
We should have a dedicated dev note for all things Block Bindings that talks about all the new stabilized API's etc. Assigned to @artemiomorales [Draft]

• Block Bindings: Open the stable editor APIs #65713
• Block Bindings: Use post meta label from register_meta in block bindings workflows #65099
• Block Bindings: Allow only admin users to create and modify bindings by default #64570
• Block Bindings: Create utils to update or remove bindings #64102
• Block bindings: UI for connecting bindings #62880
• Block bindings: Bring bindings UI in Site Editor #64072
• Block Bindings: Fix showing bindings field values in theme templates #65639

Interactivity API Updates
@DAreRodz or @michalczaplinski , can you help with this?

• Interactivity API: Add getServerState() and getServerContext() #65151
• Script Modules: Move data passing to 6.7 compat file #64006

Components Package Updates

@mirka @ciampo have volunteered to help with this :)

• Composite: stabilize APIs #63569 - @ciampo [Draft]
• FormTokenField: Deprecate bottom margin #63491 @mirka [Draft]
• CustomSelectControl: switch to ariakit-based implementation #63258 @ciampo
• CustomSelectControl V2 legacy adapter: stabilize experimental props #63248 @ciampo
• AlignmentMatrixControl: Promote to stable #60913 @ciampo
• BoxControl: Promote to stable #65469 @ciampo
• Modal: Decrease close button size #65131 @mirka [Draft]
• Deprecate DimensionControl #64951 @ciampo
• Normalize block inspector controls spacing #64526 @mirka [Draft]
• Deprecate bottom margin on BaseControl-based components #64408 @mirka [Draft]
• Button: Stabilize __experimentalIsFocusable prop #62282 - @mirka [Draft]
• SelectControl: Infer value type from options #64069 - @mirka [Draft]
• DateTime: Create TimeInput component and integrate into TimePicker #60613 @mirka [Draft]
• ToggleGroupControl: support disabled options #63450 @ciampo
• Navigator: stabilize and export APIs #64613 @ciampo

Miscellaneous Editor Updates (TBD)

• Adding Font size presets UI #63057 - @matiasbenedetto [Draft]
• Make useStyleOverride public #63656 - @ellatrix
• Try: Post content: Add clearfix #63690 - @carolinan
• ContentOnly: Add support for block styles on top-level contentOnly locked blocks #64872 - @ntsekouras
• Heading: Enable heading level curation #63535 - @ndiego
• Core Data: Support entities in the 'canUser' selector #63322 - @Mamaduka
• Global Styles: Create new public function to make it easier to expose style variations from other themes #63318 - @scruffian
• block.json: Allow passing filename as variations field #62092 - @ockham - [Draft]
• Post Date & Comment Date: Add relative date format #62298 - @amitraj2203 - [Draft]
• Global Styles: Add a typesets section to Typography #62539 - @scruffian
• Style engine: export util to compile CSS custom var from preset string #64490 - @ramonjd - [Draft]
• Media & Text: don't use background-image #64981 - @sgomes
• Add useEvent and revamped useResizeObserver to @wordpress/compose #64943 - @DaniGuardiola - [Draft]
• Locked Templates: blocks with contentOnly locking should not be transformable #64917 - @ramonjd [Draft]
• Global Styles: allow read access to users with edit_posts capabilities #65071 - @ramonjd - [Draft]
• Hooks: add support for async filters and actions #64204 - @jsnajdr
• Patterns: add opt out preference to the 'Choose a Pattern' modal when adding a page #65026 - @ramonjd [Draft]
• Stabilize the PreSavePost and SavePost filters #64198 - @jsnajdr

Query Loop Updates
@ryanwelcher would you be able to help write a dev note for these changes?

• Set query loop to have the inherit value by default #63362
• Update Inherited Query Loop value from Template Settings changes #63358
• Move Posts Per Page, Offset, and Pages controls from the block toolbar into Inspector Controls #58207
• Query loop / Post template: Enable post format filter #64167
• Query Loop: Default to querying posts when on singular content #65067
• Query Loop Block: remove Posts List variation #63404 - @ellatrix

Consolidating and expanding block supports
@mumtahinafaguni Would you be able to draft a dev note that includes all these updates in one post? 🤔

• Buttons: Add border, color, and padding block supports #63538
• Categories List: Add border block support #63950
• Column: Enable border radius support #63924
• Comment Author Name: Add Border Support #64550
• Comment Content: Add Border Support #64230
• Comment Date: Add Border Support #64210
• Comment Template: Add Border Block Support #64238
• Comment Edit Link: Add Border Block Support #64239
• Comment Reply Link: Add border support #64271
• File: Add border block support #64509
• Gallery: Add border block support #63428
• Group: Add block support for shadow #63295
• Heading: Add border support #63539
• Image: Adopt margin block support #63546
• Latest comments: Add color block support #63419
• List: Add border support #63540
• List Item: Add border support #63541
• Media Text: Add border support #63542
• Paragraph: Add border support #63543
• Post Author Biography: Add Border Support #64615
• Post Author Name: Add Border Support #64530
• Post Author: Add Border Support #64599
• Post Comments Form: Add Border Block Support #64233
• Post content block: add background image and padding support  #62499
• Post Date: Add border block support #64023
• Post Excerpt: Add border block support #64022
• Post Terms: Add border block support #64246
• Post Title: Add border block support  #64024
• Preformatted: Add border block support  #64302
• Query Title: Add Border Support #64581
• Quote: Add spacing supports #63545
• Quote blocks: add background image and minimum height support #62497
• Search: Add margin support #63547
• Site Tagline: Add border block support  #63778
• Site Title: Add border block support  #63631
• Social Links: Add border block support  #63629
• Tag Cloud: Add border block support  #63579
• Term Description: Add border block support #63630
• Verse block: add background image and minimum height support #62498
• Add writing mode support to other blocks #62727

[matiasbenedetto]

It is an end user feature but I think developers should be aware of it.

Gotcha 👍 , here it goes:

---

Font Size Presets UI

A new UI feature has been introduced in the Global Styles section of the editor, allowing users to add, edit, and remove font size presets.

A font size preset is a predefined font size that can be reused throughout the site via the font size picker. This enhancement provides a more user-friendly way to manage font size options, which were previously only accessible via the manual edition of theme.json file. Users can now modify preset names, base sizes, enable or disable the default fluid behavior, and customize the minimum and maximum values for fluid font size presets directly from the UI.

To access this interface, navigate to the Styles sidebar, then go to Typography → Font Sizes.

[cbravobernal]

@artemiomorales started an initial draft of the dev note for block bindings 🚀

[DaniGuardiola]

Hi @fabiankaegy, responding to #64943 (comment) here :)

I think the dev notes could go like:

---

New useEvent utility in @wordpress/compose

The new useEvent utility creates a stable callback that has access to the latest state (as opposed to a useCallback call with an empty dependency array). This is useful to "untrack" dependencies in a callback that is called within event handlers or effects. It cannot be called at render time.

This is a common pattern in React, and it's even being considered as a core React feature (see the RFC). More context can be found in this popular issue in the React repository.

Here's an example:

 function Component( props ) {
   const onClick = useEvent( props.onClick );
   useEffect( () => {
     onClick();
     // Won't trigger the effect again when `props.onClick` is updated.
   }, [ onClick ] );
   // Won't re-render `Button` when `props.onClick` is updated (if `Button` is
   // wrapped in `React.memo`).
   return <Button onClick={ onClick } />;
 }

New useResizeObserver API in @wordpress/compose

The new API and behavior of useResizeObserver is meant as a thin wrapper for the browser-native ResizeObserver API, which enables more use cases and better composition. The previous API is still supported, though it is considered legacy and deprecated.

Now, you must pass a callback as the first argument to the hook which is forwarded to the ResizeObserver constructor. The hook returns a setter that must be passed as a callback ref to the target element, or called in an effect in advanced use-cases. Additional options for the internal ResizeObserver.observe call can be passed as the second argument.

Here's an example:

const setElement = useResizeObserver(
  ( resizeObserverEntries ) => console.log( resizeObserverEntries ),
  { box: 'border-box' }
);
<div ref={ setElement } />;

// The setter can be used in other ways, for example:
useLayoutEffect( () => {
  setElement( document.querySelector( `data-element-id="${ elementId }"` ) );
}, [ elementId ] );

---

Let me know if that works! :)

[sgomes]

• Media & Text: don't use background-image #64981 - @sgomes

As of #64981, the Media & Text block now uses an img element instead of using CSS background-image when the "Crop image to fill" option is enabled, removing the last usage of background-image in this block. This means that, when rendering the post, all the usual performance benefits of using image elements will now be applied, such as having the image load lazily when appropriate, and letting the browser choose the most appropriate image size from the list of generated sizes.

Please feel free to rephrase as needed! 👍

[ntsekouras]

Regarding #64872 I think it will work best if we have a paragraph for related small enhancements.

A parent block's style variations are now surfaced for contentOnly locked groups. This way styles can still be applied cohesively across the group of blocks.

[ockham]

@fabiankaegy Here's a Dev Note for #62092:

block.json: variations field can now be set to name of PHP file that generates block variations

Previously, the variations field in a block.json file could be used to provide a static list of the block's variations (i.e., an array). Alternatively, the block's variation_callback could be set during server-side block registration to point to a PHP function to generate those variations.
As of WordPress 6.7, it is also possible to set the variations field to a string, which will then be interpreted as the filename of a PHP file that generates the variations (akin to how the render field works):

{ "variations": "file:./variations.php" }

Refer to the docs for more information.

---

LMK if this is alright!

[ockham]

@fabiankaegy

The following items should probably also move to the 6.7 Core documentation board:

• Block Hooks: Allow insertion as first or last child of Template Part block
• Block Hooks: "multiple": false not respected

(I've started working on those Dev Notes already.)

Edit: Draft available here.

[DaniGuardiola]

@fabiankaegy FYI my note had a typo:

-New `useResizeObserver` API in `@wordpress/components`
+New `useResizeObserver` API in `@wordpress/compose`

I edited the comment to correct it. Thanks @mirka for spotting this!

[ryanwelcher]

@fabiankaegy here is the dev note for the Query Loop block - preview is here

Updates to the Query Loop block in WordPress 6.7

WordPress 6.7 brings a number of improvements and changes to the Query Loop block.

The controls to set how many items to display, the offset and max number of pages, have been moved from the block toolbar to the Inspector Sidebar. This change standardizes the location of all of the query controls in the UI, making it much easier to find them.

Query Loop blocks that are inserted into single page, post, or custom post type now no longer display the Query Type control and defaults to querying posts. When using the block on templates, the Posts per page setting is now inherited by the block.

A new filter was added to allow filtering by Post Formats and the Posts List variation was removed due to some inconsistencies in how the block would receive defaults.

[mirka]

@fabiankaegy My dev note for #64526 (added at the bottom of the PR description) is actually a note for the Block Inspector (@wordpress/block-editor) and not the components package, so I'm thinking it should be separate from the other components package notes.

[artemiomorales]

@fabiankaegy I've updated the issue description to include the Block Bindings dev note draft and updated myself to be the assignee.

[ciampo]

@fabiankaegy all dev notes in the "Components Package Updates" section (excluding #64526, as explained above) are in this draft post. Feel free to tweak it as needed !

[DAreRodz]

@fabiankaegy, here is the dev note draft for the Interactivity API's getServerState()/getServerContext() functions.

[lezama]

@fabiankaegy, here is a draft for Extending PreviewOptions. Please let me know if you need anything else, thanks!

[stokesman]

@fabiankaegy, I’ve made a draft for #64351. I'm a first-timer on dev notes so I hope it’s mostly usable.

[fabiankaegy]

@lezama Thank you :) The Dev Notes looks great from my perspective. Are you able to publish it on the Make Core blog yourself or do you need help with that? :)

[fabiankaegy]

@ciampo @mirka The Components Package Dev note looks great 💯 It is ready to be published 👍

[bph]

I'll prepare a 6.7 Roster of design tools per block (WordPress 6.6 edition)

[jsnajdr]

Dev notes for #64204 and #64198:

Support for async actions and filters in @wordpress/hooks

The @wordpress/hooks package has a couple of new functions for running async actions and filters, allowing plugin authors to conveniently register async (promise-based) handlers and make sure that they are run in series, one after another, waiting until the previous async handler finishes.

You can register an async function as an action or a filter handler:

import { addAction, addFilter } from '@wordpress/hooks';

addAction( 'action', 'handler', async () => {
  await doSomethingAsync();
} );

addFilter( 'filter', 'handler', async ( value ) => {
  return await modifyValueAsync( value );
} );

In the filter handler, the value is always a synchronous value (not a promise) and the handler function returns a promise that resolves to an updated value.

Then you can run the filter with a newly introduced applyFiltersAsync function:

import { applyFiltersAsync } from '@wordpress/hooks';

const filteredValue = await applyFiltersAsync( 'filter', initialValue );

and similarly you can also run an action with the new doActionAsync function:

import { doActionAsync } from '@wordpress/hooks';

await doActionAsync( 'action' );

The runner functions make sure that handlers are run after each other, in a series. And that when a handler throws an error (or returns a rejected promise), the whole run is aborted and further handlers are not called. The error is propagated and becomes the result of the entire applyFiltersAsync/doActionAsync call.

New filters to customize and extend behavior of post save

There are two new hooks (one filter and one action) that allow plugin authors to customize and extend what happens when a post is being saved.

First, there is the (async) editor.preSavePost filter that receives two arguments:

• edits is an object that contains the id of the saved post and the modified attributes. The filter can modify the edits and it will be this modified object that will be sent to the server as the payload of the save POST request. The filter can also abort the save, e.g., when some custom validation fails, by throwing an error or returning a rejected promise.
• options is a read-only second argument that contains an isAutosave (boolean) field that lets the filter distinguish between regular saves and autosaves, and also an isPreview field that indicated whether the saved post is a draft intended to be previewed.

The handler can be async, as the filter is being applied using the new applyFiltersAsync function:

addFilter( 'editor.preSavePost', 'handler', async ( edits, options ) => {
  if ( ! await customValidation( edits ) ) {
    throw new Error( 'validation failed' );
  }
  return edits;
} );

The second new hook is the (async) editor.savePost action which is run after the post is saved and lets you perform additional work after the save. For example, the Gutenberg post editor itself uses this action to save legacy metaboxes for the post. This action also receives two arguments: first argument is an object with an id field, which is the saved post ID, and the second argument is options object, the same one as in the editor.preSavePost action.

[bph]

@fabiankaegy the Design Tools roster for 6.7 post is ready for review

[colorful-tones]

here is a draft for Extending PreviewOptions.

The new plugin extensibility PreviewOptions is a great addition. Thanks for the amazing contribution! 👏

I read through the draft, and I'm wondering if we could add a tiny bit more code example to answer the immediate question that every developer would likely have after seeing how to create a new PluginPreviewMenuItem: How can I manipulate or influence the editor canvas? 🤔

Otherwise, adding a menu item is merely half the idea, and many developers will be left wanting more. The additional code should be very simple and just leave a breadcrumb for developers to know where or which API to look for next if they want to influence the editor's canvas with their newly added PluginPreviewMenuItem.

Perhaps my suggestion is outside the focus of a Dev Note, and I will defer to @fabiankaegy and others to guide us.

[fabiankaegy]

@colorful-tones thank you for that callout. From my understanding the API here provides none of that. It literally only allows you to render a button / link there so you can redirect someone somewhere else / trigger your own code from there. @lezama feel free to correct me if I'm wrong/ missing something :)

[lezama]

It literally only allows you to render a button / link there so you can redirect someone somewhere else / trigger your own code from there

That’s correct! Further improvements are being proposed here: #65005.