Block schema and block supports docs: Add dimensions and position settings #48057

andrewserong · 2023-02-14T00:43:57Z

What?

Now that dimensions.minHeight and position.sticky block supports have been backported and released as part of the WordPress 6.2 Beta, this PR proposes documenting those block supports as part of the block schema, with entries in the block supports documentation.

Why?

It's good to ensure that the new features are documented prior to the release.

How?

Update block.json schema with entries for dimensions.minHeight and position.sticky.
Update block supports documentation with entries for the above, following the structure of the existing entry for spacing support.
Update theme.json docs to reflect that sticky position is opted in as part of the appearance tools.

Testing Instructions

Proofread to make sure there are no technical or grammatical issue 🙂

github-actions · 2023-02-14T01:14:51Z

Flaky tests detected in f24c3e9.
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/4178681735
📝 Reported issues:

[Flaky Test] should always expand single line selection #39787 in specs/editor/various/multi-block-selection.test.js
[Flaky Test] should leave a scheduled page scheduled if canceled #47499 in specs/editor/various/switch-to-draft.test.js
[Flaky Test] should make the modal content focusable when it is scrollable #48067 in /test/e2e/specs/editor/various/a11y.spec.js
[Flaky Test] should revert a scheduled page to a draft if confirmed #47500 in specs/editor/various/switch-to-draft.test.js

aaronrobertshaw

Thanks for staying on top of this part of the documentation @andrewserong 👍

It all reads pretty well for me.

I did spot a few typos when reviewing the modified files but they weren't introduced in this PR. There were also some minor nit-picky improvements to grammar e.g. removing unnecessary commas etc.

The diff below covers everything I've noted above. Feel free to either apply it whole or cherry pick out changes that you agree with.

Note: Given the markdown in the diff, it might be easier to copier if you edit this review comment and copy the raw diff.

Example diff for suggested tweaks

diff --git a/docs/reference-guides/block-api/block-supports.md b/docs/reference-guides/block-api/block-supports.md
index 94f461819e..2e5f509f6d 100644
--- a/docs/reference-guides/block-api/block-supports.md
+++ b/docs/reference-guides/block-api/block-supports.md
@@ -475,7 +475,7 @@ _**Note:** Since WordPress 6.2._
 -   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).
+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: {
@@ -485,7 +485,7 @@ supports: {
 }

-When the block declares support for a specific dimensions property, the attributes definition is extended to include the style attribute.
+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.:

@@ -518,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.

supports: {
@@ -578,7 +578,7 @@ _**Note:** Since WordPress 6.2._
-   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).
+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.

@@ -590,7 +590,7 @@ supports: {
}

-When the block declares support for a specific position property, the attributes definition is extended to include the style attribute.
+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.:

@@ -614,7 +614,7 @@ attributes: {
- 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.
+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.

supports: {
@@ -626,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.:

diff --git a/schemas/json/block.json b/schemas/json/block.json
index f9aa59deaa..ad3bb45516 100644
--- a/schemas/json/block.json
+++ b/schemas/json/block.json
@@ -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": {

@@ -306,7 +306,7 @@
},
"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, 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 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",

@@ -322,7 +322,7 @@
},
"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": {

@@ -342,7 +342,7 @@
},
"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, 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 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",

@@ -353,7 +353,7 @@
},
"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": [

@@ -411,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
  				}
  			}

@@ -460,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",

diff --git a/schemas/json/theme.json b/schemas/json/theme.json
index 932c03fcf1..d2fb13b6f1 100644
--- a/schemas/json/theme.json
+++ b/schemas/json/theme.json
@@ -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": "*"

</details>

aaronrobertshaw

As we discussed @andrewserong, I've pushed the local commit I had here after reviewing.

LGTM 🚢

andrewserong · 2023-02-14T05:49:57Z

Just given this a rebase to see if it'll get the performance tests passing again 🤞

andrewserong added [Type] Developer Documentation Documentation for developers [Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi labels Feb 14, 2023

andrewserong requested review from apeatling, tellthemachines and aaronrobertshaw February 14, 2023 00:43

andrewserong requested a review from ajlende as a code owner February 14, 2023 00:43

andrewserong self-assigned this Feb 14, 2023

andrewserong requested review from ajitbohra, ryanwelcher, juanmaguitar and fabiankaegy as code owners February 14, 2023 00:43

andrewserong changed the title ~~Schema and docs: Add dimensions and position settings~~ Block schema and block supports docs: Add dimensions and position settings Feb 14, 2023

aaronrobertshaw reviewed Feb 14, 2023

View reviewed changes

aaronrobertshaw approved these changes Feb 14, 2023

View reviewed changes

andrewserong enabled auto-merge (squash) February 14, 2023 03:06

andrewserong force-pushed the update/docs-and-schema-to-introduce-dimensions-and-position-supports branch from a4aacdf to 1d1e391 Compare February 14, 2023 05:49

andrewserong and others added 2 commits February 15, 2023 09:32

Schema and docs: Add dimensions and position settings

93cfff3

Fix typos and nit picks

f24c3e9

andrewserong force-pushed the update/docs-and-schema-to-introduce-dimensions-and-position-supports branch from 1d1e391 to f24c3e9 Compare February 14, 2023 22:32

andrewserong merged commit 0c208a7 into trunk Feb 14, 2023

andrewserong deleted the update/docs-and-schema-to-introduce-dimensions-and-position-supports branch February 14, 2023 23:47

github-actions bot added this to the Gutenberg 15.2 milestone Feb 14, 2023

andrewserong mentioned this pull request Mar 5, 2023

Docs: Add position: sticky to the Opt-in into UI controls appearanceTools section #48763

Merged

t-hamano mentioned this pull request Mar 24, 2023

Theme JSON schema: Add position.sticky and dimensions.minHeight properties to settings #49335

Merged

bph mentioned this pull request Jul 20, 2023

Docs: Update Appearance Tools #52785

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Block schema and block supports docs: Add dimensions and position settings #48057

Block schema and block supports docs: Add dimensions and position settings #48057

andrewserong commented Feb 14, 2023

github-actions bot commented Feb 14, 2023 •

edited

Loading

aaronrobertshaw left a comment

aaronrobertshaw left a comment

andrewserong commented Feb 14, 2023

Block schema and block supports docs: Add dimensions and position settings #48057

Block schema and block supports docs: Add dimensions and position settings #48057

Conversation

andrewserong commented Feb 14, 2023

What?

Why?

How?

Testing Instructions

github-actions bot commented Feb 14, 2023 • edited Loading

aaronrobertshaw left a comment

Choose a reason for hiding this comment

aaronrobertshaw left a comment

Choose a reason for hiding this comment

andrewserong commented Feb 14, 2023

github-actions bot commented Feb 14, 2023 •

edited

Loading