Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some documentation about the Styles UI components #49720

Merged
merged 2 commits into from
Apr 12, 2023
Merged

Add some documentation about the Styles UI components #49720

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c46616a
Add some documentation about the Styles UI components
youknowriad Apr 11, 2023
f026f53
Fix indentation
youknowriad Apr 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 129 additions & 16 deletions packages/block-editor/src/components/global-styles/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,7 @@ import { useGlobalStylesReset } from '@wordpress/block-editor';
function MyComponent() {
const [ canReset, reset ] = useGlobalStylesReset();

return canReset
? <Button onClick={ () => reset() }>Reset</Button>
: null;
return canReset ? <Button onClick={ () => reset() }>Reset</Button> : null;
}
```

Expand All @@ -25,17 +23,25 @@ function MyComponent() {
A React hook used to retrieve the styles array and settings to provide for block editor instances based on the current global styles.

```js
import { useGlobalStylesOutput, BlockEditorProvider, BlockList } from '@wordpress/block-editor';
import {
useGlobalStylesOutput,
BlockEditorProvider,
BlockList,
} from '@wordpress/block-editor';

function MyComponent() {
const [ styles, settings ] = useGlobalStylesOutput();

return <BlockEditorProvider settings={{
styles,
__experimentalFeatures: settings
}}>
<BlockList />
</BlockEditorProvider>
return (
<BlockEditorProvider
settings={ {
styles,
__experimentalFeatures: settings,
} }
>
<BlockList />
</BlockEditorProvider>
);
}
```

Expand All @@ -48,12 +54,16 @@ import { useGlobalStyle } from '@wordpress/block-editor';

function MyComponent() {
// Text color for the site root.
const [ color, setColor ] = useGlobalStyle( 'color.text' );
const [ color, setColor ] = useGlobalStyle( 'color.text' );

// The user modified color for the core paragraph block.
const [ pColor, setPColor ] = useGlobalStyle( 'color.text', 'core/paragraph', 'user' );
const [ pColor, setPColor ] = useGlobalStyle(
'color.text',
'core/paragraph',
'user'
);

return "Something";
return 'Something';
}
```

Expand All @@ -66,12 +76,115 @@ import { useGlobalSetting } from '@wordpress/block-editor';

function MyComponent() {
// The theme color palette.
const [ colorPalette, setColorPalette ] = useGlobalSetting( 'color.palette.theme' );
const [ colorPalette, setColorPalette ] = useGlobalSetting(
'color.palette.theme'
);

// The theme color palette for the paragraph block, ignoring user changes.
// If the palette is not defined for the paragraph block, the root one is returned.
const [ pColor, setPColor ] = useGlobalSetting( 'color.palette.theme', 'core/paragraph', 'base' );
const [ pColor, setPColor ] = useGlobalSetting(
'color.palette.theme',
'core/paragraph',
'base'
);

return "Something";
return 'Something';
}
```

## UI Components

The global styles folder also offers a set of reusable UI components. These components follow a strict set of guidelines:

- They are independent of any context or any store dependency. They only rely on the props passed to them.
- They receive a similar set of props:

- `value`: The value is a style object that maps closely the format used in `theme.json` and is also very close to the format of the `style` attributes for blocks. There are some differences with the block attributes due to the iteration process and the fact that we need to maintain compatibility with the existing blocks even if they predate the introduction of Global Styles and these UI components. An example value for a style object is:

```js
{
color: {
text: 'var:preset|color|blue',
background: '#FF0000',
},
typography: {
fontFamily: 'var:preset|font-family|base',
fontSize: '10px',
lineHeight: 1.5,
},
spacing: {
padding: 'var:preset|spacing|medium',
},
elements: {
link: {
color: {
text: 'var:preset|color|green',
},
},
},
}
```

- `onChange`: A callback that receives the new value and is called when the user changes the value of the UI component.
- `inheritedValue`: The inherited value is a style object that represents the combined value of the style inherited from the parent context in addition to the style applied to the current context. The format is the same as the `value` prop.
- `settings`: The settings are the theme.json settings. They are used to provide the UI components with the necessary information to render the UI. An example value for the settings is:

```js
{
color: {
palette: {
custom: [
{
slug: 'black',
color: '#000000',
},
{
slug: 'white',
color: '#FFFFFF',
},
{
slug: 'blue',
color: '#0000FF',
},
]
},
gradients: {
custom: [
{
slug: 'gradient-1',
gradient: 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
},
{
slug: 'gradient-2',
gradient: 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
},
]
},
},
typography: {
fontSizes: [
{
slug: 'small',
size: '12px',
},
{
slug: 'medium',
size: '16px',
},
{
slug: 'large',
size: '24px',
},
],
}
}
```
- `defaultControls`: The default controls are the controls that are used by default to render the UI. They are used to provide the UI components with the necessary information to render the UI. An example value for the default controls for the `ColorPanel` component is:

```js
{
background: true,
text: true,
link: true,
},
```
Comment on lines +182 to +190
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for starting the discussion about what the defaults for each of the panels should be over in #49389 (comment).

Something I was wondering about from that comment — should the defaults across the components be defaulting to false to follow the behaviour in block.json where we explicitly flag which ones we reveal? I know that in the site editor they're all displayed by default, but at the component level, I wasn't sure which idea would be preferable. Some example ideas:

  • The component as it lives in the block editor package specifies the defaults across the board (e.g. most are hidden by default, except for child layout controls). It is then up to other use cases (e.g. global styles) to specify if they'd like to reveal more controls by default. Or:
  • At the component level, we default to displaying everything by default. It is then up to the consumer to be more restrictive if it so wishes (e.g. the block.json behaviour).

What do you think?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My strong opinion is that the behavior should be the same.
My other opinion that is a bit less strong is that there's also a third option which is for us to be opinionated about what the defaults should be, that way consumers of the component (think of a component as its own unit, independent of the existing usage) itself shouldn't have to provide that prop or a big object to actually choose what to show, they should have sane defaults. And since we control what is shown or hidden on Global Styles (as opposed to the blocks), I don't see why global styles shouldn't be using these sane defaults. (at least at the root level, as there's an argument that block level should also follow the block.json config)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anyway, let's continue this discussion with Isabel in the other thread and update the documentation when we find a solution.