-
Notifications
You must be signed in to change notification settings - Fork 4.2k
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.
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
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
Flaky tests detected in f24c3e9. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4178681735
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 ofobject
type with no default assigned. This is added whenminHeight
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 ofobject
type with no default assigned. This is added whensticky
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 ofobject
type with no default assigned. This is added whenmargin
orpadding
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>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As we discussed @andrewserong, I've pushed the local commit I had here after reviewing.
LGTM 🚢
a4aacdf
to
1d1e391
Compare
Just given this a rebase to see if it'll get the performance tests passing again 🤞 |
1d1e391
to
f24c3e9
Compare
What?
Now that
dimensions.minHeight
andposition.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?
block.json
schema with entries fordimensions.minHeight
andposition.sticky
.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 🙂