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.

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

Conversation

andrewserong
Copy link
Contributor

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 🙂

@andrewserong 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 andrewserong self-assigned this Feb 14, 2023
@andrewserong 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
@github-actions
Copy link

github-actions bot commented Feb 14, 2023

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:

Copy link
Contributor

@aaronrobertshaw aaronrobertshaw left a 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 tweaksdiff --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>

Copy link
Contributor

@aaronrobertshaw aaronrobertshaw left a 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 🚢

@andrewserong andrewserong enabled auto-merge (squash) February 14, 2023 03:06
@andrewserong 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
Copy link
Contributor Author

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

@andrewserong 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 andrewserong merged commit 0c208a7 into trunk Feb 14, 2023
@andrewserong andrewserong deleted the update/docs-and-schema-to-introduce-dimensions-and-position-supports branch February 14, 2023 23:47
@github-actions github-actions bot added this to the Gutenberg 15.2 milestone Feb 14, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants