From 88b883a020bd19d1a5046630d8add3d7457bccdf Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Tue, 26 May 2020 10:52:25 +0200 Subject: [PATCH 1/6] Docs: Extend details about features integration with `theme.json` --- .../developers/themes/theme-json.md | 76 ++++++++++--------- 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md index cb1a39c69a429d..73012fc8160363 100644 --- a/docs/designers-developers/developers/themes/theme-json.md +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -14,7 +14,7 @@ This is documentation for the current direction and work in progress about how t The Block Editor surface API has evolved at different velocities, and it's now at a point where is showing some growing pains, specially in areas that affect themes. Examples of this are: the ability to [control the editor programmatically](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/), or [a block style system](https://github.com/WordPress/gutenberg/issues/9534) that facilitates user, theme, and core style preferences. -This describes the current efforts to consolidate the various APIs into a single point: a `experimental-theme.json` file. +This describes the current efforts to consolidate the various APIs into a single point – a `experimental-theme.json` file that should be located inside the root of the theme directory. When this file is present a few Block Editor mechanisms are activated. @@ -38,13 +38,13 @@ The specification for the `experimental-theme.json` follows the three main funct ``` { - presets: { - color: [ ... ], - font-size: [ ... ], - gradient: [ ... ], + "presets": { + "color": [ ... ], + "font-size": [ ... ], + "gradient": [ ... ], }, - styles: { ... }, - features: { ... } + "styles": { ... }, + "features": {... } } ``` @@ -52,20 +52,20 @@ The file is divided into sections that represent different contexts: individual ``` { - global: { - presets: { ... }, - styles: { ... }, - features: { ... } + "global": { + "presets": { ... }, + "styles": { ... }, + "features": { ... } }, - core/paragraph: { - presets: { ... }, - styles: { ... }, - features: { ... } + "core/paragraph": { + "presets": { ... }, + "styles": { ... }, + "features": { ... } }, - core/group: { - presets: { ... }, - styles: { ... }, - features: { ... } + "core/group": { + "presets": { ... }, + "styles": { ... }, + "features": { ... } } } ``` @@ -74,19 +74,25 @@ Some of the functions are context-dependant. Take, as an example, the drop cap: ``` { - global: { - features: { - dropCap: false + "global": { + "features": { + "typography": { + "dropCap": false + } } }, - core/paragraph: { - features: { - dropCap: true, + "core/paragraph": { + "features": { + "typography": { + "dropCap": true + } } }, - core/image: { - features: { - dropCap: true + "core/image": { + "features": { + "typography": { + "dropCap": true + } } } } @@ -105,17 +111,17 @@ The generated CSS Custom Properties follow this naming schema: `--wp--preset--{p For this input: ``` -presets: { - color: [ +"presets": { + "color": [ { - slug: 'strong-magenta', - value: #a156b4, + "slug": "strong-magenta", + "value": "#a156b4" }, { - slug: 'very-dark-grey', - value: #444, + "slug": "very-dark-grey", + "value": "#444" } - ], + ] } ``` From 8e28af24a270744708a27e7b85c027a226965f26 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Tue, 26 May 2020 12:01:44 +0200 Subject: [PATCH 2/6] Docs: Explain the order of processing for block editor features --- .../developers/themes/theme-json.md | 74 +++++++++++++++---- 1 file changed, 59 insertions(+), 15 deletions(-) diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md index 73012fc8160363..8ffd0c6d3229ee 100644 --- a/docs/designers-developers/developers/themes/theme-json.md +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -34,7 +34,7 @@ The Block Editor already allows the control of specific features such as alignme ## Specification -The specification for the `experimental-theme.json` follows the three main functions described in the section above: presets, styles, and features. +The specification for the `experimental-theme.json` follows the three main functions described in the section above: `presets`, `styles`, and `features`. ``` { @@ -76,7 +76,7 @@ Some of the functions are context-dependant. Take, as an example, the drop cap: { "global": { "features": { - "typography": { + "typography": { "dropCap": false } } @@ -98,7 +98,7 @@ Some of the functions are context-dependant. Take, as an example, the drop cap: } ``` -In the example above, we aim to encapsulate that the drop cap should be disabled globally but enabled in the paragraph context. The drop cap in the image context wouldn't make sense so should be ignored. +In the example above, we aim to encapsulate that the drop cap should be disabled globally but enabled in the paragraph context. The drop cap in the Image block context wouldn't make sense based on the current implementation so would be ignored, but it could be used by plugins that extend its functionality. ## Current Status @@ -111,17 +111,19 @@ The generated CSS Custom Properties follow this naming schema: `--wp--preset--{p For this input: ``` -"presets": { - "color": [ - { - "slug": "strong-magenta", - "value": "#a156b4" - }, - { - "slug": "very-dark-grey", - "value": "#444" - } - ] +"global": { + "presets": { + "color": [ + { + "slug": "strong-magenta", + "value": "#a156b4" + }, + { + "slug": "very-dark-grey", + "value": "#444" + } + ] + } } ``` @@ -172,7 +174,49 @@ The list of properties that are currently exposed via this method are: ### Features -This is being implemented, so it's not currently available. +So far, this function is only enabled for the `global` section in `experimental-theme.json`. + +``` +{ + "global": { + "features": { + "typography": { + "dropCap": false + } + } + } +} +``` + +Then each block can decide to override how they handle block editor features during their registration process (`register_block_type` or `registerBlockType` calls) using `supports` object in `block.json` file: + +``` +{ + "supports": { + "__experimentalFeatures": { + "typography": { + "dropCap": true + } + } + } +} +``` + +Moving forward, we plan to integrate overrides targeting individual blocks defined inside `experimental-theme.json` file that would be applied on top of features defined by block authors in `supports` property. + +Finally, this is how it can be used in the block's `edit` implementation: + +```js +// edit.js + +const Edit = ( props ) => { + const isDisabled = ! useEditorFeature( 'typography.dropCap', false ); + // ... +}; +``` + +The list of features that are currently supported are: +- Paragraph: drop cap. ### Recap of current available functions From 583ea7f1e292c2c559d55f84744f4fd662eaefca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= Date: Wed, 27 May 2020 07:35:03 +0200 Subject: [PATCH 3/6] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Andrés --- docs/designers-developers/developers/themes/theme-json.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md index 8ffd0c6d3229ee..42f3624ef60538 100644 --- a/docs/designers-developers/developers/themes/theme-json.md +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -123,7 +123,7 @@ For this input: "value": "#444" } ] - } + } } ``` @@ -210,7 +210,7 @@ Finally, this is how it can be used in the block's `edit` implementation: // edit.js const Edit = ( props ) => { - const isDisabled = ! useEditorFeature( 'typography.dropCap', false ); + const isDisabled = ! useEditorFeature( 'typography.dropCap' ); // ... }; ``` From aa79bb7933caf1a33e93353ef2d273e33d8bb356 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Wed, 27 May 2020 07:41:02 +0200 Subject: [PATCH 4/6] Improve formatting in the theme.json document --- .../developers/themes/theme-json.md | 38 +++++++++---------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md index 42f3624ef60538..9e9690726f0073 100644 --- a/docs/designers-developers/developers/themes/theme-json.md +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -78,21 +78,21 @@ Some of the functions are context-dependant. Take, as an example, the drop cap: "features": { "typography": { "dropCap": false - } + } } }, "core/paragraph": { "features": { "typography": { "dropCap": true - } + } } }, "core/image": { "features": { "typography": { "dropCap": true - } + } } } } @@ -174,7 +174,14 @@ The list of properties that are currently exposed via this method are: ### Features -So far, this function is only enabled for the `global` section in `experimental-theme.json`. +Via the features key we allow controlling some editor and block features according to the following rules: +- The features within `global` override the default editor settings, which plugins can modify by hooking into the `block_editor_settings` filter on the server. +- The features within the context of each block override the default block settings, which plugins can modify by hooking into the `blocks.registerBlockType` filter on the client. +- Block settings take precedence over global settings. + +For example, if a feature is enabled for a block by default, although the theme disables it at the global level, the block keeps it enabled. If the theme wants to override a block's default, it has to target that particular block. + +So far, this function is enabled only for the `global` section in `lib/experimental-default-theme.json`. ``` { @@ -182,9 +189,9 @@ So far, this function is only enabled for the `global` section in `experimental- "features": { "typography": { "dropCap": false - } - } - } + } + } + } } ``` @@ -196,24 +203,13 @@ Then each block can decide to override how they handle block editor features dur "__experimentalFeatures": { "typography": { "dropCap": true - } - } + } + } } } ``` -Moving forward, we plan to integrate overrides targeting individual blocks defined inside `experimental-theme.json` file that would be applied on top of features defined by block authors in `supports` property. - -Finally, this is how it can be used in the block's `edit` implementation: - -```js -// edit.js - -const Edit = ( props ) => { - const isDisabled = ! useEditorFeature( 'typography.dropCap' ); - // ... -}; -``` +Moving forward, we plan to integrate overrides targeting individual blocks defined inside a theme specific file (`experimental-theme.json`) that would be applied on top of features defined by block authors in `supports` property. The list of features that are currently supported are: - Paragraph: drop cap. From 9cfaabeeea277df6a6710a20b6522e25af4077ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 5 Jun 2020 10:11:18 +0200 Subject: [PATCH 5/6] Fix rebase issues --- .../developers/themes/theme-json.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md index 9e9690726f0073..98a0fc75de3734 100644 --- a/docs/designers-developers/developers/themes/theme-json.md +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -250,25 +250,69 @@ The list of features that are currently supported are: }, "core/paragraph": { "styles": { + "color": { + "background": , + "text": + }, + "typography": { + "fontSize": , + "lineHeight": + } + } + }, + "core/heading/h1": { + "styles": { + "color": { + "background": , + "text": + }, "typography": { "fontSize": , "lineHeight": }, + "typography": { + "fontSize": , + "lineHeight": + } + } + }, + "core/heading/h3": { + "styles": { "color": { "background": , "text": + }, + "typography": { + "fontSize": , + "lineHeight": } } }, "core/heading/h1": { "styles": { + "color": { + "background": , + "text": + }, "typography": { "fontSize": , "lineHeight": }, + "typography": { + "fontSize": , + "lineHeight": + } + } + }, + "core/heading/h6": { + "styles": { "color": { "background": , "text": + }, + "typography": { + "fontSize": , + "lineHeight": } } }, From 240bdf427bcf1c9c46e50cdbdcc081f54852607c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 5 Jun 2020 11:09:29 +0200 Subject: [PATCH 6/6] Fix rebase issues --- .../developers/themes/theme-json.md | 66 ++----------------- 1 file changed, 5 insertions(+), 61 deletions(-) diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md index 98a0fc75de3734..161ca5f9d7c558 100644 --- a/docs/designers-developers/developers/themes/theme-json.md +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -233,7 +233,7 @@ The list of features that are currently supported are: "value": }, { } - ], + ], "gradient": [ { "slug": , @@ -266,17 +266,13 @@ The list of features that are currently supported are: "background": , "text": }, - "typography": { - "fontSize": , - "lineHeight": - }, "typography": { "fontSize": , "lineHeight": } } }, - "core/heading/h3": { + "core/heading/h2": { "styles": { "color": { "background": , @@ -288,23 +284,19 @@ The list of features that are currently supported are: } } }, - "core/heading/h1": { + "core/heading/h3": { "styles": { "color": { "background": , "text": }, - "typography": { - "fontSize": , - "lineHeight": - }, "typography": { "fontSize": , "lineHeight": } } }, - "core/heading/h6": { + "core/heading/h5": { "styles": { "color": { "background": , @@ -316,63 +308,15 @@ The list of features that are currently supported are: } } }, - "core/heading/h2": { - "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, - "color": { - "background": , - "text": - } - } - }, - "core/heading/h3": { - "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, - "color": { - "background": , - "text": - } - } - }, - "core/heading/h4": { + "core/heading/h6": { "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, "color": { "background": , "text": - } - } - }, - "core/heading/h5": { - "styles": { - "typography": { - "fontSize": , - "lineHeight": }, - "color": { - "background": , - "text": - } - } - }, - "core/heading/h6": { - "styles": { "typography": { "fontSize": , "lineHeight": - }, - "color": { - "background": , - "text": } } },