Gutenberg: Block editor: Controlling the Block Editor

[gziolo]

Related: #6023, #6941, #7806. #7931, #8732, #14110 #15450, #18892.

The full story was shared by @youknowriad over a month ago:
https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/

I'm including the most important bits below:

One of the important use-cases of the block-editor is the possibility to control the experience programmatically. Controlling the experience means allowing agencies and developers to configure or restrict the usage of the different features available in the editor. This has always been one of the priorities while adding features to Gutenberg and it will continue to be.

As shown above, the block editor already provides a big number of APIs to control the experience, but it’s fair to acknowledge a lack of consistency and a few missing APIs (for instance to disable drop caps in Paragraph blocks).

In order to address this, I’m proposing a new block_editor_features hook that looks like this:

// Non-exhaustive representation of the block-editor configuration options.
$block_editor_features = array(
    'colors' => array(
        "enabled" => true,
        "colorPalette" => array(),
        "allowCustomColors" => true,
        "gradientPalette" => array(),
        "allowCustomGradients" => true,
    ),
    'typography' => array(
        "enabled" => true,
        "fontSizes" => array(),
        "allowCustomFontSizes" => true,
        "allowDropCap" => true,
    ),
);

apply_filters( 'block_editor_features', array $block_editor_features, WP_Post $post );

And these would be made available to block authors using a dedicated selector.

const features = wp.data.select( 'core/block-editor' ).getFeatures();

In addition to the PHP filter, this configuration can also be made available in the proposed theme.json file.

There is also an expectation to have more grained control over features – to be able to apply customizations on the block type level as well. It's going to be explored as part of this work taking into account many existing issues where such capability was requested.

Tasks

• [x] Make useEditorFeature aware of theme.json block specific configs. #24416
• [x] Allow defining presets (color, font size and gradients) in theme.json.
  
  
  
  • [x] Either create a usePreset('colors') hook or consolidate to useEditorFeature('color.preset').
  
  
• [x] Allow enabling/disabling custom colors, custom gradients, custom font sizes in theme.json. #24761 #24964 #25038
• [x] Allow enabling/disabling drop cap support.
• [x] Allow enabling/disabling line-height controls. #25043
• [x] Allow enabling/disabling and defining custom units. #25217
• [x] Allow enabling/disabling spacing controls. #25141
• [x] Allow enabling/disabling link control support. #25148
• [ ] Document the APIs.
• [ ] Make theme.json stable.

[ligne13]

Is this coming to core soon ?

[rezziemaven]

I would also like to know, thanks in advance. I may have missed where I could find the timeline on when this feature would be released.

[gziolo]

It's in active development. The next major WordPress release (5.5) is scheduled around August this year and it's the earliest when it can be included. I hope to get some initial APIs exposed in Gutenberg plugin in late April.

[rezziemaven]

Thanks @gziolo for the update! Fingers crossed that the team would be able to expose the API by late April! I'm especially interested in the ability to remove/ disable inspector or toolbar controls using this feature.

[gziolo]

I talked to @youknowriad and he proposed using the following structure for theme.json where config section is responsible for defining block editor features. It's still something uncertain as there are too many moving parts involved:

{
   "global": {
      "color": "var( --my-palette-color-one )",
      "background": "var( --my-palette-color-two)",
      "font-size": "var( --my-font-size)"
   },
   "blocks": {
       "h2": {
           "font-size": "calc( var( --my-font-size) * 2 )"
       }
   },
   "config": {
       "color": {
           "palette": [],
           "allowCustomColors": true,
           "gradientPalette": [],
           "allowCustomGradients": true
       },
       "typography": {
            "fontSizes": [],
            "allowCustomFontSize": true,
            "allowDropCap": true
        },
        "blocks": {
            "core/paragraph": {
                "color": {
                   "palette": [],
                   "allowCustomColors": false
                }
            }
        }
   },
   "ui": {
       "palette": true,
       "custom": {
           "--my-font-size": { "type": "fontsize" },
           "--random-variable": { "type": "number" }
       }
   }
}

[hatsumatsu]

This looks promising. I'm wondering whether the config is supposed to work as an allow- or deny-list.

If there is a config in place what happens when new features or core blocks are introduced? Are they blocked by default or enabled with default settings?

The second option would imply that theme authors need to closely track future changes to the editor to achieve a consistent experience.

[gziolo]

I'm starting extended leave later this week (3 months) and I won't be able to finish this task until I'm back. If anyone wants to take over this task, feel free to do so :)

The current behavior is documented at https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/themes/theme-json.md#features.

The most important missing features have their own issues created:

• Allow a theme to override settings per block for editor features (#22657)
• Allow a theme to override global defaults for editor features (#22655)

[nosolosw]

I'll take this over.

[rezziemaven]

Hi @nosolosw. I know you just took this over, but I was wondering if you would know it's likely that this will still be included in the 5.5 release. I see it's not a part of the WordPress 5.5 Must Have project but still wanted to verify.

[nosolosw]

hi @rezziemaven, no, this isn't going to make it to 5.5.

[nosolosw]

We've progressed a good bit and when https://github.com/WordPress/gutenberg/pull/25148 lands we'll have this shape for the features object:

{
  "features": {
    "typography": {
      "dropCap": true
    },
    "color": {
      "custom": true,
      "link": true
    },
    "gradient": {
      "custom": true
    },
    "fontSize": {
      "custom": true
    },
    "lineHeight": {
      "custom": false
    }
  }
}

Note that we only define 6 settings here.

There are a few things I don't like with the current approach: how verbose it is and that there's no conceptual clarity/hierarchy (ex: there's a typography section but also fontSize & lineHeigh; link color is within color, but gradient is not). These are some alternatives I can think of:

-- Plain approach:

{
  "features": {
    "customColor": true,
    "customFontSize": true,
    "customGradient": true,
    "customLineHeight": true,
    "dropCap": true,
    "linkColor": true
  }
}

-- Group by categories, as we do in styles:

{
  "features": {
    "typography": {
      "customFontSize": true,
      "customLineHeight": true,
      "dropCap": true
    },
    "color": {
      "customColor": true,
      "customGradient": true,
      "link": true
    }
  }
}

A related question I have is what we're going to do with things like align-wide, core-block-patterns, responsive-embeds. I don't see them in the above list of tasks and it seems to me that those should also be absorbed (at least, I don't understand why they don't). Whether or not we absorb this in theme.json should inform the object shape.

[youknowriad]

• I think "align-wide" is also a theme.json thing but it's a bit special. Basically, I think at some point we need to rethink alignments entirely, probably too soon to move this one.
• patterns are probably something outside of theme.json (at least for now)
• responsive-embeds: I have no idea what this is about :P but we should definitely do an audit of the block editor settings and see what makes sense as theme.json configs instead.

[nosolosw]

@youknowriad and I talked about this and we see two options:

1. For each context (global, core/paragraph, etc), we'd have three sections: presets, features, and styles. The API to get values in the client would consint of two hooks: usePreset( color ) and useEditorFeature( color.customGradient ).

{
  "presets": {
    "color": [],
    "gradient": [],
    "fontSize": []
  },
  "features": {
    "typography": {
      "customFontSize": true,
      "customLineHeight": true,
      "dropCap": true
    },
    "color": {
      "customColor": true,
      "customGradient": true,
      "link": true
    },
    "spacing": {
      "custom": false,
      "units": ["px", "em", "rem", "vh", "vw"]
    }
  },
  "styles": {
    "typography": {
      "fontSize": "value",
      "lineHeight": "value"
    },
    "color": {
      "text": "value",
      "background": "value",
      "gradient": "value"
    }
  }
}

1. We have two sections within each context, features and styles (preset becomes part of features). Only one hook in the client useEditorFeature( color.preset ), useEditorFeature( gradient.custom ):

{
  "features": {
    "typography": {
      "dropCap": true
    },
    "color": {
      "custom": true,
      "link": true,
      "preset": []
    },
    "gradient": {
      "custom": true,
      "preset": []
    },
    "fontSize": {
      "custom": true,
      "preset": []
    },
    "lineHeight": {
      "custom": false,
      "preset": []
    },
    "spacing": {
      "custom": false,
      "units": ["px", "em", "rem", "vh", "vw"],
      "preset": []
    }
  },
  "styles": {
    "typography": {
      "fontSize": "value",
      "lineHeight": "value"
    },
    "color": {
      "text": "value",
      "background": "value",
      "gradient": "value"
    }
  }
}

[nosolosw]

Personally, I lean towards the first option.

It's a bit of everything: conceptually, presets, features, and styles make sense to me; when it comes to writing them down, presets take a lot of space (see) so it's good that we have them isolated and don't disturb when reading the features section, for example; it can also be convenient code-wise for things like internationalization (the wp-cli would only need to parse the presets section for finding strings to translate).

cc @mtias @jorgefilipecosta

[cbirdsong]

Has there been any consideration for how child themes would override portions of this configuration? It seems like the editor could just merge the parent/child files before applying them, but I also have zero knowledge of the implementation and how practical/impractical that idea is.

[ZebulanStanphill]

I think most of the time font style presets should combine font size and line height into a single preset, since the two are closely connected. Do these formats account for that? Similarly, it would be good to be able to define preset color schemes.

[nosolosw]

@cbirdsong child themes support was a low priority so far given that we're still stabilizing theme.json. With the recent announcement of TwentyTwentyOne as a _teaching tool_ for others, I've gone ahead and created a specific issue for it https://github.com/WordPress/gutenberg/issues/25612