Skip to content

Commit

Permalink
Block schema and block supports docs: Add dimensions and position set…
Browse files Browse the repository at this point in the history 
…tings (#48057)

* Schema and docs: Add dimensions and position settings

* Fix typos and nit picks

---------

Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com>
  • Loading branch information
@andrewserong @aaronrobertshaw
andrewserong and aaronrobertshaw committed Feb 14, 2023
1 parent 7a8a44a commit 0c208a7
Show file tree
Hide file tree
Showing 4 changed files with 107 additions and 15 deletions.
75 changes: 72 additions & 3 deletions docs/reference-guides/block-api/block-supports.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -466,6 +466,39 @@ supports: {
}
```

## dimensions

_**Note:** Since WordPress 6.2._

- Type: `Object`
- Default value: null
- Subproperties:
- `minHeight`: type `boolean`, default value `false`

This value signals that a block supports some of the CSS style properties related to dimensions. When it does, the block editor will show UI controls for the user to set their values if [the theme declares support](/docs/how-to-guides/themes/theme-json/#opt-in-into-ui-controls).

```js
supports: {
dimensions: {
minHeight: true // Enable min height control.
}
}
```

When a block declares support for a specific dimensions property, its attributes definition is extended to include the `style` attribute.

- `style`: attribute of `object` type with no default assigned. This is added when `minHeight` support is declared. It stores the custom values set by the user, e.g.:

```js
attributes: {
style: {
dimensions: {
minHeight: "50vh"
}
}
}
```

## html

- Type: `boolean`
Expand All @@ -485,7 +518,7 @@ supports: {
- Type: `boolean`
- Default value: `true`
By default, all blocks will appear in the inserter, block transforms menu, Style Book, etc. To hide a block from all parts of the user interface so that it can only be inserted programatically, set `inserter` to `false`.
By default, all blocks will appear in the inserter, block transforms menu, Style Book, etc. To hide a block from all parts of the user interface so that it can only be inserted programmatically, set `inserter` to `false`.
```js
supports: {
Expand Down Expand Up @@ -536,6 +569,42 @@ supports: {
}
```

## position

_**Note:** Since WordPress 6.2._

- Type: `Object`
- Default value: null
- Subproperties:
- `sticky`: type `boolean`, default value `false`

This value signals that a block supports some of the CSS style properties related to position. When it does, the block editor will show UI controls for the user to set their values if [the theme declares support](/docs/how-to-guides/themes/theme-json/#opt-in-into-ui-controls).

Note that sticky position controls are currently only available for blocks set at the root level of the document. Setting a block to the `sticky` position will stick the block to its most immediate parent when the user scrolls the page.

```js
supports: {
position: {
sticky: true // Enable selecting sticky position.
}
}
```

When the block declares support for a specific position property, its attributes definition is extended to include the `style` attribute.

- `style`: attribute of `object` type with no default assigned. This is added when `sticky` support is declared. It stores the custom values set by the user, e.g.:

```js
attributes: {
style: {
position: {
type: "sticky",
top: "0px"
}
}
}
```

## spacing

- Type: `Object`
Expand All @@ -545,7 +614,7 @@ supports: {
- `padding`: type `boolean` or `array`, default value `false`
- `blockGap`: type `boolean` or `array`, default value `false`

This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values, if [the theme declares support](/docs/how-to-guides/themes/theme-support.md#cover-block-padding).
This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values if [the theme declares support](/docs/how-to-guides/themes/theme-support.md#cover-block-padding).

```js
supports: {
Expand All @@ -557,7 +626,7 @@ supports: {
}
```

When the block declares support for a specific spacing property, the attributes definition is extended to include the `style` attribute.
When the block declares support for a specific spacing property, its attributes definition is extended to include the `style` attribute.

- `style`: attribute of `object` type with no default assigned. This is added when `margin` or `padding` support is declared. It stores the custom values set by the user, e.g.:

Expand Down
1 change: 1 addition & 0 deletions docs/reference-guides/theme-json-reference/theme-json-living.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ Setting that enables the following UI tools:
- border: color, radius, style, width
- color: link
- dimensions: minHeight
- position: sticky
- spacing: blockGap, margin, padding
- typography: lineHeight

Expand Down
42 changes: 32 additions & 10 deletions schemas/json/block.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -269,22 +269,22 @@
"properties": {
"background": {
"type": "boolean",
"description": "This property adds UI controls which allow the user to apply a solid background color to a block.\n\nWhen color support is declared, this property is enabled by default (along with text), so simply setting color will enable background color.\n\nTo disable background support while keeping other color supports enabled, set to false.\n\nWhen the block declares support for color.background, the attributes definition is extended to include two new attributes: backgroundColor and style",
"description": "This property adds UI controls which allow the user to apply a solid background color to a block.\n\nWhen color support is declared, this property is enabled by default (along with text), so simply setting color will enable background color.\n\nTo disable background support while keeping other color supports enabled, set to false.\n\nWhen the block declares support for color.background, its attributes definition is extended to include two new attributes: backgroundColor and style",
"default": true
},
"gradients": {
"type": "boolean",
"description": "This property adds UI controls which allow the user to apply a gradient background to a block.\n\nGradient presets are sourced from editor-gradient-presets theme support.\n\nWhen the block declares support for color.gradient, the attributes definition is extended to include two new attributes: gradient and style",
"description": "This property adds UI controls which allow the user to apply a gradient background to a block.\n\nGradient presets are sourced from editor-gradient-presets theme support.\n\nWhen the block declares support for color.gradient, its attributes definition is extended to include two new attributes: gradient and style",
"default": false
},
"link": {
"type": "boolean",
"description": "This property adds block controls which allow the user to set link color in a block, link color is disabled by default.\n\nLink color presets are sourced from the editor-color-palette theme support.\n\nWhen the block declares support for color.link, the attributes definition is extended to include the style attribute",
"description": "This property adds block controls which allow the user to set link color in a block, link color is disabled by default.\n\nLink color presets are sourced from the editor-color-palette theme support.\n\nWhen the block declares support for color.link, its attributes definition is extended to include the style attribute",
"default": false
},
"text": {
"type": "boolean",
"description": "This property adds block controls which allow the user to set text color in a block.\n\nWhen color support is declared, this property is enabled by default (along with background), so simply setting color will enable text color.\n\nText color presets are sourced from the editor-color-palette theme support.\n\nWhen the block declares support for color.text, the attributes definition is extended to include two new attributes: textColor and style",
"description": "This property adds block controls which allow the user to set text color in a block.\n\nWhen color support is declared, this property is enabled by default (along with background), so simply setting color will enable text color.\n\nText color presets are sourced from the editor-color-palette theme support.\n\nWhen the block declares support for color.text, its attributes definition is extended to include two new attributes: textColor and style",
"default": true
},
"enableContrastChecker": {
Expand All @@ -304,14 +304,25 @@
"description": "When the style picker is shown, a dropdown is displayed so the user can select a default style for this block type. If you prefer not to show the dropdown, set this property to false.",
"default": true
},
"dimensions": {
"type": "object",
"description": "This value signals that a block supports some of the CSS style properties related to dimensions. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.\n\nWhen the block declares support for a specific dimensions property, its attributes definition is extended to include the style attribute.",
"properties": {
"minHeight": {
"type": "boolean",
"description": "Allow blocks to define a minimum height value.",
"default": false
}
}
},
"html": {
"type": "boolean",
"description": "By default, a block’s markup can be edited individually. To disable this behavior, set html to false.",
"default": true
},
"inserter": {
"type": "boolean",
"description": "By default, all blocks will appear in the inserter, block transforms menu, Style Book, etc. To hide a block from all parts of the user interface so that it can only be inserted programatically, set inserter to false.",
"description": "By default, all blocks will appear in the inserter, block transforms menu, Style Book, etc. To hide a block from all parts of the user interface so that it can only be inserted programmatically, set inserter to false.",
"default": true
},
"multiple": {
Expand All @@ -329,9 +340,20 @@
"description": "A block may want to disable the ability to toggle the lock state. It can be locked/unlocked by a user from the block 'Options' dropdown by default. To disable this behavior, set lock to false.",
"default": true
},
"position": {
"type": "object",
"description": "This value signals that a block supports some of the CSS style properties related to position. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.\n\nWhen the block declares support for a specific position property, its attributes definition is extended to include the style attribute.",
"properties": {
"sticky": {
"type": "boolean",
"description": "Allow blocks to stick to their immediate parent when scrolling the page.",
"default": false
}
}
},
"spacing": {
"type": "object",
"description": "This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values, if the theme declares support.\n\nWhen the block declares support for a specific spacing property, the attributes definition is extended to include the style attribute.",
"description": "This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.\n\nWhen the block declares support for a specific spacing property, its attributes definition is extended to include the style attribute.",
"properties": {
"margin": {
"oneOf": [
Expand Down Expand Up @@ -389,16 +411,16 @@
},
"typography": {
"type": "object",
"description": "This value signals that a block supports some of the CSS style properties related to typography. When it does, the block editor will show UI controls for the user to set their values, if the theme declares support.\n\nWhen the block declares support for a specific typography property, the attributes definition is extended to include the style attribute.",
"description": "This value signals that a block supports some of the CSS style properties related to typography. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.\n\nWhen the block declares support for a specific typography property, its attributes definition is extended to include the style attribute.",
"properties": {
"fontSize": {
"type": "boolean",
"description": "This value signals that a block supports the font-size CSS style property. When it does, the block editor will show an UI control for the user to set its value.\n\nThe values shown in this control are the ones declared by the theme via the editor-font-sizes theme support, or the default ones if none is provided.\n\nWhen the block declares support for fontSize, the attributes definition is extended to include two new attributes: fontSize and style",
"description": "This value signals that a block supports the font-size CSS style property. When it does, the block editor will show an UI control for the user to set its value.\n\nThe values shown in this control are the ones declared by the theme via the editor-font-sizes theme support, or the default ones if none is provided.\n\nWhen the block declares support for fontSize, its attributes definition is extended to include two new attributes: fontSize and style",
"default": false
},
"lineHeight": {
"type": "boolean",
"description": "This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if the theme declares support.\n\nWhen the block declares support for lineHeight, the attributes definition is extended to include a new attribute style of object type with no default assigned. It stores the custom value set by the user. The block can apply a default style by specifying its own style attribute with a default",
"description": "This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if the theme declares support.\n\nWhen the block declares support for lineHeight, its attributes definition is extended to include a new attribute style of object type with no default assigned. It stores the custom value set by the user. The block can apply a default style by specifying its own style attribute with a default",
"default": false
}
}
Expand Down Expand Up @@ -438,7 +460,7 @@
},
"attributes": {
"type": "object",
"description": "Set the attribues for the block example"
"description": "Set the attributes for the block example"
},
"innerBlocks": {
"type": "array",
Expand Down
4 changes: 2 additions & 2 deletions schemas/json/theme.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
"type": "object",
"properties": {
"appearanceTools": {
"description": "Setting that enables the following UI tools:\n\n- border: color, radius, style, width\n- color: link\n- dimensions: minHeight\n- spacing: blockGap, margin, padding\n- typography: lineHeight",
"description": "Setting that enables the following UI tools:\n\n- border: color, radius, style, width\n- color: link\n- dimensions: minHeight\n- position: sticky\n- spacing: blockGap, margin, padding\n- typography: lineHeight",
"type": "boolean",
"default": false
}
Expand Down Expand Up @@ -332,7 +332,7 @@
"type": "object",
"properties": {
"operator": {
"description": "With + or * depending on whether scale is generated by increment or mulitplier.",
"description": "With + or * depending on whether scale is generated by increment or multiplier.",
"type": "string",
"enum": [ "+", "*" ],
"default": "*"
Expand Down

1 comment on commit 0c208a7

@github-actions
Copy link

Choose a reason for hiding this comment

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

Flaky tests detected in 0c208a7.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4179130873
📝 Reported issues:

Please sign in to comment.