[wp-trac] [WordPress Trac] #55485: Clarify `wp_should_load_separate_core_block_assets()`, `block.json` script expectations

[WordPress Trac]

#55485: Clarify `wp_should_load_separate_core_block_assets()`, `block.json` script
expectations
---------------------------+-----------------------------
 Reporter:  jeremyfelt     |      Owner:  (none)
     Type:  defect (bug)   |     Status:  new
 Priority:  normal         |  Milestone:  Awaiting Review
Component:  Script Loader  |    Version:
 Severity:  normal         |   Keywords:
  Focuses:  docs           |
---------------------------+-----------------------------
 In the `block.json`
 [https://github.com/WordPress/gutenberg/blob/45a8e6be0eb7fca87d64ce8140792b30e6bc4a20/schemas/json/block.json
 schema], the `script` property is described as:

 > "Block type frontend and editor script definition. It will be enqueued
 both in the editor and when viewing the content on the front of the site."

 From that description, I expect the `script` set in my block's
 `block.json` to load in the editor and on the front-end when my block is
 in use. I do not expect the script to load on the front-end when my block
 is not in use.

 If I activate TwentyTwentyTwo, everything works as expected.

 If I activate TwentyTwentyOne, my script appears on every front-end view,
 whether or not the block is loaded.

 The cause of this can be tracked to
 `wp_should_load_separate_core_block_assets()`, which has a short
 description of:

 > Checks whether separate styles should be loaded for core blocks on-
 render

 This implies at the beginning of the function documentation that the
 function will only apply to **core** blocks.

 The longer description helps a bit, but is muddied up in talking about
 core and third-party blocks separately when in reality it seems that they
 are treated the same. It mentions `block-library/style.css`, which itself
 implies this _might_ be talking about styles rather than all assets.

 The filter inside the function, `should_load_separate_core_block_assets`,
 defaults to `false` for themes that are not FSE and has a short
 description of:

 > Filters whether block styles should be loaded separately.

 The longer description refers only to "core block assets".

 -----
 == Proposal

 My guess is that we can't just change the filter to default to `true`,
 though that would be ideal. :)

 I think the function docs could be clarified with something like:

 {{{
 /**
  * Checks whether block assets should always load or only on-render.
  *
  * When this function returns true, block assets defined by the `script`
 and
  * `style` properties in `block.json` are loaded on-render.
  *
  * When this function returns false, these block assets are always loaded,
  * regardless of whether the block is rendered in a page.
  *
  * This only affects front end and not the block editor screens.
 }}}

 And the filter docs with something like:

 {{{
  * Filters whether block assets should always load or load only on-render.
  *
  * Returning false loads all block assets, regardless of whether they are
 rendered
  * in a page or not. Returning true loads block assets only when they are
 rendered.
 }}}

 Previously #53505

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/55485>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform