Consistency and coherence for the high level UI components to edit styles (global styles and block styles)

[youknowriad]

The UI components we have right now to edit styles (colors, typography, dimensions...) grew organically based on use-cases over time but overall we lack consistency and organisation in our code base:

• We first added small components: ColorPanels, FontSizePickers, Toggles...
• Then we tied these to block supports while retaining the old ones for BC and custom usage
• We sometimes moved things between sidebar and block toolbars
• Now we have Global Styles that duplicate some of the components and reuses some
• The props and settings between all these components lack consistency and coherence.

It is becoming very hard to maintain as we keep iterating and introducing new props, special cases, duplicate components...

Is there a way we can improve the situation and clarify:

• The role of each component
• its input/ouput
• the way we document these components
• how to add new components
• how to add new styles
• Can we enable all of that by staying consistent and enable future use-cases (like saving block supports into a linked global styles record for the Template Part block).

Solution

Here's a potential (maybe naive) solution.

Examples

// This one edits gradient and background color and update the style object.
<BackgroundColorControl
  value={ style }
  onChange={ onChange }
  settings={ settings }
  inherit={ inheritedStyle }
  // Extra custom props are possible in some special case but we should limit them
  enableConstrastChecker
/>

// This one edits just the text control and update the style object.
<TextColorControl
  value={ style }
  onChange={ onChange }
  settings={ settings }
  inherit={ inheritedStyle }
/>

// This one edits all colors for a given context and updates the style object.
// This includes BackgroundColorControl and TextColorControl...
<ColorsControl
  value={ style }
  onChange={ onChange }
  settings={ settings }
  inherit={ inheritedStyle }
/>

// This one edits the font size and update the style object.
<FontSizeControl
  value={ style }
  onChange={ onChange }
  settings={ settings }
  inherit={ inheritedStyle }
/>

// This one edits the font family and update the style object.
<FontFamilyControl
  value={ style }
  onChange={ onChange }
  settings={ settings }
  inherit={ inheritedStyle }
/>

// This one edits all typography styles and update the style object.
// This includes FontSizeControl and FontFamilyControl...
<TypographyControl
  value={ style }
  onChange={ onChange }
  settings={ settings }
  inherit={ inheritedStyle }
>

Base Principles:

• All components receive the exact same props and format for the props:
• The value prop corresponds to the actual style object for the current context (context could block instance, root global styles, block context in global styles, or element context in global styles). The format of the object can be close to the one used in Global Styles.
• The onChange is just a callback triggered upon change of the value prop.
• The settings corresponds to the whole settings object of the current context, it would contain things like "enable/disable things", presets... The format of that object can be close the one used in Global Styles as well.
• The inherit prop is also a "style object" similar to the value prop but it contains the style that is inherited from parent contexts (it can be optional for a start but it's useful in some situtations)

Flexible usage

// Using the components in Block Supports or Custom Blocks
<BackgroundColorControl
  value={ getStyleFromAttributes( attributes ) }
  onChange={ ( value ) => onChangeAttributes( getAttributesFromStyle( value ) ) }
  settings={ getSettingsForCurrentBlock() }
/>

// Using the components in GlobalStyles
<BackgroundColorControl
  value={ getStyleFromGlobalStylesContext( contextName ) }
  onChange={ ( value ) => onChangeGlobalStyles( contextName, getGlobalStyleObjectFromValue( value ) ) }
  settings={ getSettingsForCurrentGlobalStylesContext( contextName ) }
/>

• getStyleFromAttributes, getAttributesFromStyle, getSettingsForCurrentBlock, getStyleFromGlobalStylesContext, getGlobalStyleObjectFromValue and getSettingsForCurrentGlobalStylesContext are all functions that we build once and use everywhere.

Potential downside

• Performance due to the intermediary "style" and "settings" objects?

Open Questions

• What do you think about the approach, is this something that will be able to absorb all of our use-cases while staying consistent.
• Where should we put these components? A package, a folder in block-editor?
• How should we document them?

cc @jorgefilipecosta @oandregal @mcsf @mtias @ciampo @gziolo @aaronrobertshaw @andrewserong

[aaronrobertshaw]

Thanks for getting this discussion going @youknowriad 🙇

What do you think about the approach, is this something that will be able to absorb all of our use-cases while staying consistent.

Overall, I really like the approach. Including the addition of the inherit prop, that'll come in handy.

The benefits from the increase in consistency across components reach beyond easing maintenance burdens to reducing barriers for people to use the components with confidence. It should also provide solid examples to follow when creating new components.

In terms of covering all our use-cases, others probably have broader experience here and can better evaluate this. For me though, it appears like it will cover global styles, block supports and ad hoc uses that I've seen, so looks promising.

My gut feel around the potential performance hit is that it could be a reasonable trade-off but it would be nice to quantify it.

Where should we put these components? A package, a folder in block-editor?

If we can make these components generic enough, I think the @wordpress/components package could be an option, and might drive their use and exposure?

How should we document them?

Another possible advantage of including the components within the @wordpress/components package could be using the Storybook to further document and demo them.

Wherever the documentation ends up, I think it would be good to define some best practices. In particular, how to use them in an ad hoc manner. For example, ensuring that an ad hoc solution's style object pulled from a block's attributes doesn't interfere with block supports or similar.

If we proceed with this proposal, let me know how I can help out, I'd like to get involved 🙂

[andrewserong]

Just a +1 I like the sound of this proposal, too! Having a clean and consistent API for these controls will be really beneficial, particularly in reducing some of the edge cases between the block editor and global styles.

I think the @wordpress/components package could be an option

That sounds good to me, too. At first glance, these components don't appear to rely on block editor state, since they're passed the style objects and callbacks that they need. So that package (or nesting them in a directory within that package) sounds like a good candidate to me!

[ciampo]

I think the @wordpress/components package could be an option

I believe that @wordpress/components should contain components that can be used to build UIs outside of gutenberg and the block editor.

The proposed components deal with settings and style objects which are quite specific to how gutenberg and the block editor work, and therefore I'm not sure that @wordpress/components is a good fit in this scenario.

Otherwise, I definitely agree that, in order to maintain a good components library, tools like Storybook and a good documentation (including best practices) are a requirement.

Even in terms of how to "signal" that these are quite a high-level components, currently we don't have any particular agreement on how to classify components in @wordpress/components yet.

[jorgefilipecosta]

The proposed components deal with settings and style objects which are quite specific to how gutenberg and the block editor work, and therefore I'm not sure that @wordpress/components is a good fit in this scenario.

I agree with this. These components receive a style shape and mutate it; I don't think they fit the component package. We already have lower-level counterparts in the components package e.g.: something that receives value onChange (as a raw value, not a style shape) and for future components, we should continue to do so. The UI should be on the components package with a very generic API, and then we have higher-level versions; now, they usually are on the block editor. I'm not sure about where they should be in the future.

Regarding a component like:

// This one edits gradient and background color and update the style object.
<BackgroundColorControl
  value={ style }
  onChange={ onChange }
  settings={ settings }
  inherit={ inheritedStyle }
  // Extra custom props are possible in some special case but we should limit them
  enableConstrastChecker
/>

The colors are implemented using PanelColorGradientSettings, a component that allows changing multiple colors at the same time and deals with things like color indications.

<PanelColorGradientSettings
			title={ __( 'Color' ) }
			colorSettings={ [
				{
					value: color.color,
					onChange: setColor,
					label: __( 'Icon Color' ),
				},
				{
					value: color.iconBackground,
					onChange: setIconBackground,
					label: __( 'Icon Background' ),
				},
			] }
</PanelColorSettings>

I'm not sure if we gain much in having each color in a component. Maybe we can have a component that includes all the colors and uses PanelColorGradientSettings inside?
We also have another challenge on the colors on the BlockEditor navigation will be based on popovers on global styles is based on navigation panels. The UI is not the same, so I'm unsure if we can reuse the ColorControl component between block-editor and global styles.

I guess we can start exploring this approach on the other controls besides colors and see where it goes, and then if it is a good fit for the other places, we can see how to make it work for the colors.

We have an issue that we can not share code between block-editor and global styles without making that code part of our public API. That causes us to fear creating reusable artifacts between the two packages. We end up duplicating code or following different logics. I think if we could share code between these two packages without it being public from the begging, we would have much more reusability, and we would see natural API's patterns to emerge.

[youknowriad]

I'm not sure if we gain much in having each color in a component.

I think having a generic component for colors has proved to be insufficient several times:

• Gradients only make sense for backgrounds
• Contrast checks need to know what is text and what is background

These components can still rely on lower level generic components if needed but for me these special cases inside the low level components are already good indicators that there's something wrong there.

We also have another challenge on the colors on the BlockEditor navigation will be based on popovers on global styles is based on navigation panels. The UI is not the same, so I'm unsure if we can reuse the ColorControl component between block-editor and global styles.

That is exactly why I'm proposing a global ColorsControl (popovers) but also lower level ones that can be used in Global styles for instance but still with the exact same no brainer API.

We have an issue that we can not share code between block-editor and global styles without making that code part of our public API.

That is not a big issue, we can either have experimental components somewhere or an internal bundled package like icons or interface.

we would see natural API's patterns to emerge.

I think at this point we have enough history with these components to be able to think holistically and build the concepts before writing the code, that's what I'm trying to do with this discussion: what patterns are emerging now? what can we learn from them and how can we move forward.

[mtias]

Gradients only make sense for backgrounds

For now! Gradients on text should come eventually #30982.

[youknowriad]

One thing that cross my mind that is not addressed in the proposal above is the fact that some blocks add additional controls to "ToolPanels" (dimensions, ...) using Slots. The questions that arise here for me is:

• Do we want things like TypographyControl and DimensionsControl to actually be a ToolsPanel? I guess it can be useful if the same exact design is also used in Global Styles but is this how things are supposed to work?
• When a block uses a ToolsPanel slot, it seems the purpose is only to extend the said panel in the block inspector and not the global styles as the attribute modified is specific to the block. meaning is it possible to consider these extra controls as just an extra children prop to support maybe and not something fundamental to the component itself?
• The other option I thought about is maybe we don't need reusable top level things: DimentionsControl, ColorsControl and TypographyControl. Maybe these are just custom things for each context?

Any thoughts here?

[noisysocks]

I know it's been over a year 😅 but could you elaborate on your last two points here? I don't quite understand what you mean.

• Do we want things like TypographyControl and DimensionsControl to actually be a ToolsPanel? I guess it can be useful if the same exact design is also used in Global Styles but is this how things are supposed to work?

The design is pretty similar nowadays! Global styles uses ToolsPanel for Typography and Dimensions.

[youknowriad]

Yeah! to be honest I don't remember entirely :P. I think I was just thinking about the implementation issues we'd face because the design between global styles and inspector can be a bit different. Especially if we take the "whole" panel as a unique component. It seems smaller things inside the panel are the same but the higher-level panels might differ a bit.