Block API: Tracking issue

Open gziolo opened this issue 2 years ago • 3 comments

This issue will track and describe a few mini-projects around improvements to the Block API.

Block Assets

Block assets are JavaScript (editorScript, script, viewScript) and CSS (editorStyle, style) defined in block.json file.

Some of the details were tracked in https://github.com/WordPress/gutenberg/issues/33542.

[x] WordPress 6.1: Add multiple assets per type (editorScript, script) to bring complete consistency to what we already have for styles (https://github.com/WordPress/wordpress-develop/pull/3108).
[ ] Introduce viewStyle for styles used only on the front end to align with scripts and viewScript.
[ ] Allow customizations for assets in block.json as explained in Trac#54018 and to fix #40447. Tracked in https://github.com/WordPress/gutenberg/issues/46954.
[ ] Develop strategies for loading JavaScript on the frontend - head vs footer, async/defer (related proposal https://github.com/WordPress/performance/issues/168). It could also cover frontend hydration techniques explored in https://github.com/WordPress/block-hydration-experiments/issues/12.
[x] Change the default behavior for viewScript when the render_callback is present in the block definition (Trac#56470).
[ ] 🛠️ Explore how to tree-shake block styles on the front end (#41020).
[ ] Start using JavaScript Modules and Import Maps (https://github.com/WordPress/gutenberg/issues/36716)

Block Registration

[ ] Register multiple blocks from several block.json files. At the moment developers have to register every block separately. It could help to update register_block_type or add new register_block_types on the server to support auto-discovery of multiple blocks through block.json in a given target folder.
[x] WordPress 6.1: Reference PHP file necessary for the block from block.json. It could be a new setting render in block.json (Trac#53148, https://github.com/WordPress/wordpress-develop/pull/3222, https://github.com/WordPress/gutenberg/pull/42430).
[ ] "Universal blocks" that could be written once and run in both PHP and JS with the help of a compiler (https://github.com/WordPress/gutenberg/discussions/38224).
[ ] Explore a mechanism to export different code depending on the context (edit, save, or frontend explored in https://github.com/WordPress/block-hydration-experiments/issues/11).
[x] WordPress 6.1: Better imports for core blocks in the Gutenberg repository and @wordpress/block-library to make it easier to consume individual blocks (https://github.com/WordPress/gutenberg/pull/42258).
[x] WordPress 6.1: Combine block metadata during the build process into one file to avoid loading too many block.json files for core blocks (see https://github.com/WordPress/wordpress-develop/pull/2252).
[ ] Start using REST API for block types in WordPress core (https://github.com/WordPress/gutenberg/issues/22812).
[ ] Consider adding SlotFill for the block's description in the sidebar to allow custom code. At the moment we use block's description which is a simple string. However, it would be sometimes useful to include some custom HTML code like <a />.
[ ] Check all default behaviors we use with Block API and find if there is anything we no longer want. Remove it completely for blocks that define “apiVersion” 3. It could align with the first version of frontend hydration.
[ ] Explore ways to automatically insert a given block in a specific parent block, for example: always include Log In/Out block in the Navigation block (https://github.com/WordPress/gutenberg/issues/39439 and https://github.com/WordPress/gutenberg/issues/37717).
[x] WordPress 6.1: Allow plugins to modify a theme.json file in a similar way themes do (https://github.com/WordPress/gutenberg/issues/41707).
[ ] Allow custom path for languages to be defined in block.json for translations used with JavaScript (Trac#54797).
[ ] Add handling for block type name aliases used with block variations (https://github.com/WordPress/gutenberg/issues/43743). They should fall back if necessary to the original block type name, e.g. woocommerce/product-list that can get resolved to the product-list variation added to the core/query block.
[ ] 🛠️ Stabilize experimental selectors API as top-level selectors field (https://github.com/WordPress/gutenberg/pull/46496)
[ ] Offer option to register a block only in a specific editor(s) (https://github.com/WordPress/gutenberg/issues/46900).

Block Attributes

[x] 🛠️ Decide what to do with the experimental role content added in #30469.
[ ] 🛠️ Decide whether to introduce an experimental role unique/internal (https://github.com/WordPress/gutenberg/pull/34750).
[x] Find a way to expose attributes for the client in the context of the frontend (https://github.com/WordPress/block-hydration-experiments/issues/13).
[ ] Create a system for inserting site/post metadata into generic blocks (https://github.com/WordPress/gutenberg/issues/37753).
[ ] Explore how to connect an individual block attribute with a given UI control and the save flow. In effect, have a simple way to allow editing block attributes without manually writing all code for block controls and inspector controls.
[ ] Exploring how Patterns can be connected to Schemas (#41606).

Block Variations

[ ] Allow block styles scoped to variations (https://github.com/WordPress/gutenberg/issues/40621).

Block Supports

[ ] 🛠️ Add missing block supports to core blocks (https://github.com/WordPress/gutenberg/issues/43241).
[ ] Stabilize all experimental APIs used today.

Inserting & Moving Blocks

[ ] Find a way to cover multiblock plugins where you have all of them installed but they wouldn’t get activated until you insert them for the first time. It’s mostly a UX challenge because you could show them in the inserter like blocks from the Block Directory, but they could get higher priority.
[ ] We have a new basic ancestor API (https://github.com/WordPress/gutenberg/pull/39894). We discussed more advanced options on the intersection of ancestor and parent. Let's explore that further.
[ ] Ensure that the block editor respects parent & ancestor when using drag & drop, or copy & paste.
[ ] Better UX to prevent nesting some blocks into self (the same Reusable Block, Template Part, Post Content, etc).

Block Editing

[ ] 🛠️ Introduce classification of block validation types to make block deprecation handling more flexible (https://github.com/WordPress/gutenberg/issues/21703).
[ ] Blocks with state or different versions like Log In/Out core block. Explore how to build UI that allows full page control over global state like the user session and feed it into the block context so users can preview blocks in different contexts.
[ ] "Undo trap": Avoid getting stuck in an editing state (https://github.com/WordPress/gutenberg/issues/8119).

Dynamic Block Manipulation

[ ] Dynamic replacement of server-provided content in blocks and in HTML attributes (https://github.com/WordPress/gutenberg/discussions/39831).
[x] 🛠️ Injecting dynamic data to block HTML markup in PHP (https://github.com/WordPress/gutenberg/pull/42485, https://make.wordpress.org/core/2022/08/19/a-new-system-for-simply-and-reliably-updating-html-attributes/).

Server-side Render Component

[ ] Correctly pass parent block context in REST API call (https://github.com/WordPress/gutenberg/issues/40714).

Documentation

[x] Cover optional block variations usage in block.json (https://github.com/WordPress/gutenberg/issues/40490, https://github.com/WordPress/gutenberg/pull/42539).

May 23 '22 12:05 gziolo

Develop strategies for loading JavaScript on the frontend - head vs footer, but also frontend hydration techniques explored in Implement different hydration techniques block-hydration-experiments#12.

This can be a good first step, but acknowledging that we need more than that in the near future: probably asycn/defer (something like what @adamsilverstein proposed in https://github.com/WordPress/performance/issues/168) or even do the jump to ESM.

Apart from that, I think we should explore a mechanism to export different code depending on the context (Edit, Save, or Frontend): https://github.com/WordPress/block-hydration-experiments/issues/11

May 23 '22 14:05 luisherranz

Thank you @luisherranz for your feedback. I included your suggestions together with references.

I also added two more items that I missed initially but have been following closely for a long time:

Introduce classification of block validation types to make block deprecation handling more flexible (https://github.com/WordPress/gutenberg/issues/21703).
"Universal blocks" that could be written once and run in both PHP and JS with the help of a compiler (https://github.com/WordPress/gutenberg/discussions/38224).

May 27 '22 13:05 gziolo

@gziolo I have reviewed the items that are already tracked here and I myself have created 3 issues recently that I think could all be added:

https://github.com/WordPress/gutenberg/issues/42548 (the one you added the comment to)
https://github.com/WordPress/gutenberg/issues/42342
https://github.com/WordPress/gutenberg/issues/38958

Jul 20 '22 11:07 fabiankaegy

☑️ Completed in WordPress 6.1 cycle

Block Registration

Reference PHP file necessary for the block from block.json. It could be a new setting render in block.json (Trac#53148, https://github.com/WordPress/wordpress-develop/pull/3222, https://github.com/WordPress/gutenberg/pull/42430).
Better imports for core blocks in the Gutenberg repository and @wordpress/block-library to make it easier to consume individual blocks (https://github.com/WordPress/gutenberg/pull/42258).
Combine block metadata during the build process into one file to avoid loading too many block.json files for core blocks (see https://github.com/WordPress/wordpress-develop/pull/2252).

Block Assets

Some of the details were tracked in https://github.com/WordPress/gutenberg/issues/33542.

Add multiple assets per type (editorScript, script) to bring complete consistency to what we already have for styles (https://github.com/WordPress/wordpress-develop/pull/3108).
Change the default behavior for viewScript when the render_callback is present in the block definition (Trac#56470).
Allow plugins to modify a theme.json file in a similar way themes do (https://github.com/WordPress/gutenberg/issues/41707).

Documentation

Cover optional block variations usage in block.json (https://github.com/WordPress/gutenberg/issues/40490, https://github.com/WordPress/gutenberg/pull/42539).

Feb 13 '23 09:02 gziolo

☑️ Completed in WordPress 6.2 cycle

Block Modification

WordPress 6.2: Injecting dynamic data to block HTML markup in PHP (https://github.com/WordPress/gutenberg/pull/42485, https://make.wordpress.org/core/2022/08/19/a-new-system-for-simply-and-reliably-updating-html-attributes/).

Feb 13 '23 09:02 gziolo

Mentioning this in case you think it'd be good to include it:

https://github.com/WordPress/gutenberg/discussions/38108

It's related to this item, but I wasn't sure it was talking about the same use case:

Explore how to build UI that allows full page control over global state like the user session and feed it into the block context so users can preview blocks in different contexts.

Feb 22 '23 17:02 luisherranz

Mentioning this in case you think it'd be good to include it:

How should we handle different layers/states for the same block in the editor? #38108

It's related to this item, but I wasn't sure it was talking about the same use case:

Yes, it was the same item so I linked it and rephrased as:

Blocks with different versions like Log In/Out block, or different states like Navigation block. Explore how to build UI that allows full page control over global states like the user session, or viewport. Feed that information into the block context so users can edit and preview blocks in different contexts.

Unrelated to that I added three action items based on recently triaged issues:

Add a new utility function to add script / viewScript to an already registered block (https://github.com/WordPress/gutenberg/issues/48382).
Add support for the ancestor and parent settings for the block variation (#48424).
Clarify the behavior of the parent when empty during block registration (https://github.com/WordPress/gutenberg/issues/15731).

Feb 26 '23 07:02 gziolo

Another set of updates applied:

Added to Block Variations: Allow users to select multiple block style variations (https://github.com/WordPress/gutenberg/issues/14598).
Added to Block Variations: Block Variations: Add PHP version of wp.blocks.registerBlockVariation (https://github.com/WordPress/gutenberg/issues/47170).
Replaced in Documentation ~Refresh README for @wordpress/blocks, which is outdated.~ with: Address confusing experiences when searching resources related to learning about block development (https://github.com/WordPress/gutenberg/issues/48638).
Added to Documentation: spacing.blockGap explanation is inadequate for custom blocks (https://github.com/WordPress/gutenberg/issues/43921).
Removed as it seems to be not general enough and useful only for a few core blocks: Allow setting role HTML attributes on blocks (#46002).

Mar 03 '23 10:03 gziolo

Sharing in case it relates to this effort and want it tracked here: one of the big tasks related to styles is being able to absorb block styles (CSS as well as the __experimentalStyle from block.json) as part of the global styles merge algorithm https://github.com/WordPress/gutenberg/issues/45198

This is: by providing block styles in a structured way, they can be merged with core, theme, and user styles into a single stylesheet. Then, decide what of those should be shipped to the front-end.

Mar 22 '23 09:03 oandregal

Sharing in case it relates to this effort and want it tracked here: one of the big tasks related to styles is being able to absorb block styles (CSS as well as the __experimentalStyle from block.json) as part of the global styles merge algorithm #45198

That's a great one. I included it for now in the "Block Assets" section as it sort of removes the need to write specific regular CSS. This is also going to be another helpful performance optimization.

Mar 23 '23 06:03 gziolo

Added new item in the Block Modification section:

Offer the ability to inject and manipulate inline dynamic tokens for blocks using Rich Text (https://github.com/WordPress/gutenberg/issues/18490 and https://github.com/WordPress/gutenberg/issues/21932).

Mar 28 '23 08:03 gziolo

Added new item in the Block Attributes section:

Optional support that optimizes handling blocks for usage as structured data (https://github.com/WordPress/gutenberg/issues/49437).

Mar 29 '23 11:03 gziolo

Consider adding SlotFill for the block's description in the sidebar to allow custom code. At the moment we use block's description which is a simple string. However, it would be sometimes useful to include some custom HTML code like <a />.

Now tracked in #49887

Apr 18 '23 08:04 jeherve

Consider adding SlotFill for the block's description in the sidebar to allow custom code. At the moment we use block's description which is a simple string. However, it would be sometimes useful to include some custom HTML code like <a />.

Now tracked in #49887

Thank you so much @jeherve. I linked the issue in the description.

I also removed the following item from the Block Attributes section:

Check whether we still need a special way or if it's only a documentation effort to expose attributes for the client in the frontend context with Interactive API in place (related to https://github.com/WordPress/block-hydration-experiments/issues/13).

There is an alternative approach that allows exposing attributes to the client covered in the Proposal: The Interactivity API – A better developer experience in building interactive blocks.

I added a new item in the Block Attributes section:

Provide a general solution to customize the list of allowed blocks for inner blocks with block attributes (https://github.com/WordPress/gutenberg/issues/15682).

Apr 18 '23 09:04 gziolo

I included a list of the current Top Things:

🛠️ https://github.com/WordPress/gutenberg/issues/49868
🛠️ https://github.com/WordPress/gutenberg/issues/50029
🛠️ https://github.com/WordPress/gutenberg/issues/44410
🛠️ https://github.com/WordPress/gutenberg/issues/48458
🛠️ https://github.com/WordPress/gutenberg/issues/39439

I also merged the "Backlog" section with "In Progress" section.

Apr 24 '23 10:04 gziolo

I added a new item to the Backlog in the Block Interactions section, it's in progress:

Offer a way to ungroup blocks with a new type of transform (https://github.com/WordPress/gutenberg/pull/50385)

May 11 '23 07:05 gziolo

In https://github.com/WordPress/gutenberg/discussions/51005, @Mamaduka is championing the proposal to create a formal API for registering new Block Supports options for blocks.

May 31 '23 08:05 gziolo

I found myself wanting for blocks to be able to export data they have. Case in point: trying to implement a feature which shows in the site editor sidebar the navigations available in a template part, when that template part is visible in the frame. I can get the client ids of the navigation blocks, but then I have to reimplement the whole logic of getting navigation details from the API although the blocks rendered already did it. I want to ask client id X give me data :)

Jun 15 '23 13:06 draganescu

Added https://github.com/WordPress/gutenberg/issues/51373 to the list.

Jun 29 '23 13:06 mtias

Something that's been on my mind lately is how we have a lot of different APIs to do with restricting blocks:

The templateLock prop on InnerBlocks and templateLock block editor setting
The lock block attribute
The allowedBlocks prop on InnerBlocks and allowedBlocks block editor setting
The parent attribute in registerBlockType
The useBlockEditingMode hook

I wonder if we can consolidate some of these APIs or otherwise make them more coherent. Perhaps something to think about in the context of Block API improvements.

Jul 20 '23 00:07 noisysocks

Update

Top Things

https://github.com/WordPress/gutenberg/issues/53740
https://github.com/WordPress/gutenberg/issues/53987
HTML API: Introduce HTML Processor
https://github.com/WordPress/gutenberg/issues/54536
https://github.com/WordPress/gutenberg/issues/48458
https://github.com/WordPress/gutenberg/issues/51373
https://github.com/WordPress/gutenberg/issues/2768

Completed during WP 6.3 & 6.4

https://github.com/WordPress/gutenberg/pull/48286
https://github.com/WordPress/gutenberg/issues/39439
https://github.com/WordPress/gutenberg/issues/49868
https://github.com/WordPress/gutenberg/issues/50866
https://github.com/WordPress/gutenberg/issues/51056
https://github.com/WordPress/gutenberg/issues/44410
Stabilize experimental selectors API as top-level selectors field (Trac #57585, https://github.com/WordPress/gutenberg/pull/46496).
Develop strategies for loading JavaScript on the frontend - head vs footer, async/defer (related proposal https://github.com/WordPress/performance/issues/168). It could also cover frontend hydration techniques explored in https://github.com/WordPress/block-hydration-experiments/issues/12.
No simple way to enqueue styles and scripts for a group of blocks (https://github.com/WordPress/gutenberg/issues/41821).
Offer a way to ungroup blocks with a new type of transform (https://github.com/WordPress/gutenberg/pull/50385).
Docs: Address confusing experiences when searching resources related to learning about block development (https://github.com/WordPress/gutenberg/issues/48638).
Docs: How to work with the templates defined with render (https://github.com/WordPress/gutenberg/issues/47826).

On hold

https://github.com/WordPress/gutenberg/issues/50029

Added

Introducing more robust permission handling across the various capabilities (block registration, locking, etc) so administrators can define what blocks are available for different user roles (or even what capabilities of individual blocks are to be exposed). See Phase 3: Collaboration, Block Library.
Offer a way to define the list of disallowed blocks to mitigate the limitation of the currently supported allowed list (https://github.com/WordPress/gutenberg/issues/49592, https://github.com/WordPress/gutenberg/issues/38500).
https://github.com/WordPress/gutenberg/issues/50229
https://github.com/WordPress/gutenberg/issues/54112
https://github.com/WordPress/gutenberg/issues/53847

Sep 05 '23 08:09 gziolo

Regarding viewStyle: The initial issue was closed, therefore I'm posting this here: I actually think this would be great to have. Not having this assumes, frontend styles can be used 1:1 in the editor. I've encountered many situations where that's just not true - it has gotten a lot better with the apiVersion: 2 blocks, but there are still many cases where I want to enqueue a style only in the frontend. Examples:

Very complex blocks - where I will develop a very specific block editing experience in the editor with components and editor styles and want to load the "real" styles for the (dynamically) rendered block only in the frontend.
JavaScript-heavy frontend - the most basic example being slider. I will have a lot of CSS which only styles the JS-initialized version of the block and they just don't need to be loaded in the editor.
There are cases where the frontend styles are just not used in the editor (and I know that while developing), so it's a performance slow-down if you have many such blocks. But there are also cases where the frontend styles may just "destroy" the editing experience of a block because they just don't work in that context.

Since we already have script, viewScript and editorScript I think it would keep clarity by also introducing viewStyle. Even if there are not many use cases where it's used, I don't see a real disadvantage. It would also mean, that all assets of a block in all contexts could be managed through block.json - which would be great.

Sep 14 '23 12:09 gaambo

@gaambo, thank you for feedback.

Regarding viewStyle: The initial issue was closed, therefore I'm posting this here:

Can you share the link to the issue? I would like to learn why it was closed and potentially reopen. There is still an item listed in the Backlog that signals that we have this API on the roadmap but it doesn't link to the issue you referred to:

"Introduce viewStyle for styles used only on the front end to align with scripts and viewScript."

Sep 14 '23 21:09 gziolo

Can you share the link to the issue? I would like to learn why it was closed and potentially reopen. There is still an item listed in the Backlog that signals that we have this API on the roadmap but it doesn't link to the issue you referred to:

@gziolo I've found #33542 where viewStyle was mentioned. I can open a new issue if required and we can link it in this overview issue.

Sep 15 '23 07:09 gaambo

I've found #33542 where viewStyle was mentioned. I can open a new issue if required and we can link it in this overview issue.

It was me who closed the issue with the note I moved the item to this issue - the one I quoted in https://github.com/WordPress/gutenberg/issues/41236#issuecomment-1720161563 😄

If you could open a new issue that would be great, thank you! I'm happy to see this feature implemented if it's going to be useful for custom blocks.

Sep 15 '23 07:09 gziolo

Update

Completed during WP 6.4

https://github.com/WordPress/gutenberg/issues/53987

Added

https://github.com/WordPress/gutenberg/issues/54904 (Top Things)
https://github.com/WordPress/gutenberg/issues/35223

Needs review

Introduce viewStyle for styles used only on the front end to align with scripts and viewScript (https://github.com/WordPress/gutenberg/pull/55492, https://github.com/WordPress/wordpress-develop/pull/5531).

Nov 03 '23 11:11 gziolo

Update

Completed during WordPress 6.5 cycle

https://github.com/WordPress/gutenberg/issues/53300
https://github.com/WordPress/gutenberg/issues/56803
https://github.com/WordPress/gutenberg/issues/54904
https://github.com/WordPress/gutenberg/issues/53705
https://github.com/WordPress/gutenberg/discussions/54579
Create a system for inserting site/post metadata into generic blocks (https://github.com/WordPress/gutenberg/issues/37753.
Provide a general solution to customize the list of allowed blocks for inner blocks with block attributes (https://github.com/WordPress/gutenberg/issues/15682, https://github.com/WordPress/gutenberg/issues/16560, https://github.com/WordPress/gutenberg/issues/14515).
Start using JavaScript Modules and Import Maps (https://github.com/WordPress/gutenberg/issues/36716).
Support for deferred block variation initialization on the server has been added, which improves performance (https://core.trac.wordpress.org/ticket/59969).
Introduce view style for styles used only on the front end to align with scripts and view script (https://github.com/WordPress/gutenberg/issues/54491, https://core.trac.wordpress.org/ticket/59673).
Asset registration file .asset.php has been made optional for blocks (https://core.trac.wordpress.org/ticket/60460).
https://github.com/WordPress/gutenberg/issues/56305

New

🔝 https://github.com/WordPress/gutenberg/issues/60956
🔝 https://github.com/WordPress/gutenberg/issues/59819
🔝 https://github.com/WordPress/gutenberg/issues/60219
🔝 https://github.com/WordPress/gutenberg/issues/60324
🔝 https://github.com/WordPress/gutenberg/issues/60252
https://github.com/WordPress/gutenberg/issues/56838
https://github.com/WordPress/gutenberg/issues/58233

Resources

Mar 15 '24 12:03 gziolo

gutenberg gutenberg copied to clipboard

Block API: Tracking issue

Block Assets

Block Registration

Block Attributes

Block Variations

Block Supports

Inserting & Moving Blocks

Block Editing

Dynamic Block Manipulation

Server-side Render Component

Documentation

☑️ Completed in WordPress 6.1 cycle

Block Registration

Block Assets

Documentation

☑️ Completed in WordPress 6.2 cycle

Block Modification

Update

Top Things

Completed during WP 6.3 & 6.4

On hold

Added

Update

Completed during WP 6.4

Added

Needs review

Update

Completed during WordPress 6.5 cycle

New

Resources

gutenberg
gutenberg copied to clipboard