Merge pull request #18 from WordPress/master

merge master back into fork

docs/designers-developers/developers/block-api/block-deprecation.md

@@ -1,19 +1,47 @@
 # Deprecated Blocks
 
-When updating static blocks markup and attributes, block authors need to consider existing posts using the old versions of their block. In order to provide a good upgrade path, you can choose one of the following strategies:
+When updating static blocks markup and attributes, block authors need to consider existing posts using the old versions of their block. To provide a good upgrade path, you can choose one of the following strategies:
 
  - Do not deprecate the block and create a new one (a different name)
  - Provide a "deprecated" version of the block allowing users opening these in the block editor to edit them using the updated block.
 
-A block can have several deprecated versions. A deprecation will be tried if a parsed block appears to be invalid, or if there is a deprecation defined for which its `isEligible` property function returns true.
+A block can have several deprecated versions. A deprecation will be tried if the current state of a parsed block is invalid, or if the deprecation defines an `isEligible` function that returns true.
+
+It is important to note that if a deprecation's `save` method does not produce a valid block then it is skipped, including its `migrate` method, even if `isEligible` would return true for the given attributes. This means that if you have several deprecations for a block and want to perform a new migration, like moving content to `InnerBlocks`, you may need to include the `migrate` method in multiple deprecations for it to be applied to all previous versions of the block.
+
+Deprecations do not operate as a chain of updates in the way other software data updates, like database migrations, do. At first glance, it is easy to think that each deprecation is going to make the required changes to the data and then hand this new form of the block onto the next deprecation to make its changes. What happens instead, is that each deprecation is passed the original saved content, and if its `save` method produces valid content the deprecation is used to parse the block attributes. If it has a `migrate` method it will also be run using the attributes parsed by the deprecation. The current block is updated with the migrated attributes and inner blocks before the current block's `save` function is run to generate new valid content for the block. At this point the current block should now be in a valid state.
+
+For blocks with multiple deprecations, it may be easier to save each deprecation to a constant with the version of the block it applies to, and then add each of these to the block's `deprecated` array. The deprecations in the array should be in reverse chronological order. This allows the block editor to attempt to apply the most recent and likely deprecations first, avoiding unnecessary and expensive processing.
+
+### Example:
+
+{% codetabs %}
+{% ESNext %}
+```js
+const v1 = {};
+const v2 = {};
+const v3 = {};
+const deprecated = [ v3, v2, v1 ];
+
+```
+{% ES5 %}
+```js
+var v1 = {};
+var v2 = {};
+var v3 = {};
+var deprecated = [ v3, v2, v1 ];
+```
+{% end %}
+
+It is also recommended to keep [fixtures](https://github.com/WordPress/gutenberg/blob/master/packages/e2e-tests/fixtures/blocks/README.md) which contain the different versions of the block content to allow you to easily test that new deprecations and migrations are working across all previous versions of the block.
 
 Deprecations are defined on a block type as its `deprecated` property, an array of deprecation objects where each object takes the form:
 
 - `attributes` (Object): The [attributes definition](/docs/designers-developers/developers/block-api/block-attributes.md) of the deprecated form of the block.
 - `supports` (Object): The [supports definition](/docs/designers-developers/developers/block-api/block-registration.md) of the deprecated form of the block.
 - `save` (Function): The [save implementation](/docs/designers-developers/developers/block-api/block-edit-save.md) of the deprecated form of the block.
-- `migrate` (Function, Optional): A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of `[ attributes, innerBlocks ]` compatible with the block.
-- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This function is not called when the block is invalid. This is particularly useful in cases where a block is technically valid even once deprecated, and requires updates to its attributes or inner blocks.
+- `migrate` (Function, Optional): A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of `[ attributes, innerBlocks ]` compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant.
+- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, and requires updates to its attributes or inner blocks. This function is not called when the results of all previous deprecations' `save` functions were invalid.
 
 It's important to note that `attributes`, `supports`, and `save` are not automatically inherited from the current version, since they can impact parsing and serialization of a block, so they must be defined on the deprecated object in order to be processed during a migration.
 

docs/designers-developers/developers/data/data-core-edit-post.md

@@ -372,10 +372,6 @@ _Returns_
 
 Returns an action object used to request meta box update.
 
-_Returns_
-
--   `Object`: Action object.
-
 <a name="setAvailableMetaBoxesPerLocation" href="#setAvailableMetaBoxesPerLocation">#</a> **setAvailableMetaBoxesPerLocation**
 
 Returns an action object used in signaling
@@ -385,10 +381,6 @@ _Parameters_
 
 -   _metaBoxesPerLocation_ `Object`: Meta boxes per location.
 
-_Returns_
-
--   `Object`: Action object.
-
 <a name="setIsInserterOpened" href="#setIsInserterOpened">#</a> **setIsInserterOpened**
 
 Returns an action object used to open/close the inserter.

docs/designers-developers/developers/slotfills/main-dashboard-button.md

@@ -1,18 +1,19 @@
 # MainDashboardButton
 
-This slot allows replacing the default main dashboard button in the post editor 
-that's used for closing the editor in fullscreen mode. In the site editor this slot
-refers to the "back to dashboard" button in the navigation sidebar.
+This slot allows replacing the default main dashboard button in the post editor and site editor. 
+It's used for returning back to main wp-admin dashboard when editor is in fullscreen mode.
 
 ## Examples
 
-Basic usage:
+### Post editor example
+
+This will override the W icon button in the header.
 
 ```js
 import { registerPlugin } from '@wordpress/plugins';
 import {
 	__experimentalMainDashboardButton as MainDashboardButton,
-} from '@wordpress/interface';
+} from '@wordpress/edit-post';
 
 const MainDashboardButtonTest = () => (
     <MainDashboardButton>
@@ -32,16 +33,14 @@ the post editor, that can be achieved in the following way:
 import { registerPlugin } from '@wordpress/plugins';
 import {
 	__experimentalFullscreenModeClose as FullscreenModeClose,
-} from '@wordpress/edit-post';
-import {
 	__experimentalMainDashboardButton as MainDashboardButton,
-} from '@wordpress/interface';
+} from '@wordpress/edit-post';
 import { close } from '@wordpress/icons';
 
 
 const MainDashboardButtonIconTest = () => (
     <MainDashboardButton>
-        <FullscreenModeClose icon={ close } />
+        <FullscreenModeClose icon={ close } href="http://wordpress.org" />
     </MainDashboardButton>
 );
 
@@ -50,13 +49,15 @@ registerPlugin( 'main-dashboard-button-icon-test', {
 } );
 ```
 
-Site editor example:
+### Site editor example
+
+In the site editor this slot refers to the "back to dashboard" button in the navigation sidebar.
 
 ```js
 import { registerPlugin } from '@wordpress/plugins';
 import {
 	__experimentalMainDashboardButton as MainDashboardButton,
-} from '@wordpress/interface';
+} from '@wordpress/edit-site';
 import {
 	__experimentalNavigationBackButton as NavigationBackButton,
 } from '@wordpress/components';

docs/designers-developers/developers/themes/theme-json.md

@@ -97,6 +97,7 @@ The settings section has the following structure and default values:
         "dropCap": true, /* false to opt-out */
         "fontFamilies": [ ... ], /* font family presets */
         "fontSizes": [ ... ], /* font size presets, as in add_theme_support('editor-font-sizes', ... ) */
+        "fontStyles": [ ... ], /* font style presets */
         "fontWeights": [ ... ], /* font weight presets */
         "textDecorations": [ ... ], /* text decoration presets */
         "textTransforms": [ ... ] /* text transform presets */
@@ -349,6 +350,7 @@ These are the current typography properties supported by blocks:
 | Context | Font Family | Font Size | Font Style | Font Weight | Line Height | Text Decoration | Text Transform |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | Global | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| Code | - | Yes | - | - | - | - | - |
 | Heading [1] | - | Yes | - | - | Yes | - | - |
 | List | - | Yes | - | - | - | - | - |
 | Navigation | Yes | Yes | Yes | Yes | - | Yes | Yes |

docs/designers-developers/developers/tutorials/block-based-themes/README.md

@@ -15,7 +15,7 @@ This tutorial is up to date as of Gutenberg version 9.1.
  1. [What is needed to create a block-based theme?](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#what-is-needed-to-create-a-block-based-theme)
  2. [Creating the theme](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#creating-the-theme)
  3. [Creating the templates and template parts](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#creating-the-templates-and-template-parts)
- 4. [Experimental-theme.json -Global styles](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#experimental-theme-json-global-styles)
+ 4. [Experimental-theme.json - Global styles](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#experimental-theme-json-global-styles)
  5. [Adding blocks](/docs/designers-developers/developers/tutorials/block-based-themes/block-based-themes-2-adding-blocks.md)
 
 ## What is needed to create a block-based theme?
@@ -34,7 +34,7 @@ A block based theme requires an `index.php` file, an index template file, a `sty
 
 The theme may optionally include an [experimental-theme.json file](/docs/designers-developers/developers/themes/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme.
 
-Templates are placed inside the block-templates folder, and template parts are placed inside the block-template-parts folder:
+Templates are placed inside the `block-templates` folder, and template parts are placed inside the `block-template-parts` folder:
 
 ```
 theme
@@ -57,7 +57,7 @@ theme
 ## Creating the theme
 
 Create a new folder for your theme in `/wp-content/themes/`.
-Inside this folder, create the block-templates and block-template-parts folders.
+Inside this folder, create the `block-templates` and `block-template-parts` folders.
 
 Create a `style.css` file. The file header in the `style.css` file has [the same items that you would use in a traditional theme](https://developer.wordpress.org/themes/basics/main-stylesheet-style-css/#explanations).
 
@@ -166,7 +166,7 @@ theme
 
 ### Creating the templates and template parts
 
-Create two template parts called `footer.html` and `header.html` and place them inside the block-template-parts folder. You can leave the files empty for now.
+Create two template parts called `footer.html` and `header.html` and place them inside the `block-template-parts` folder. You can leave the files empty for now.
 
 Inside the block-templates folder, create an `index.html` file.
 
@@ -318,7 +318,7 @@ Below are the presets and styles combined:
 ```
 {
 	"global": {
-		"setttings": {
+		"settings": {
 			"color": {
 				"palette": [
 					{

docs/manifest.json

@@ -191,6 +191,12 @@
 		"markdown_source": "../docs/designers-developers/developers/slotfills/README.md",
 		"parent": "developers"
 	},
+	{
+		"title": "MainDashboardButton",
+		"slug": "main-dashboard-button",
+		"markdown_source": "../docs/designers-developers/developers/slotfills/main-dashboard-button.md",
+		"parent": "slotfills"
+	},
 	{
 		"title": "PluginBlockSettingsMenuItem",
 		"slug": "plugin-block-settings-menu-item",

docs/toc.json

@@ -35,6 +35,7 @@
 			{ "docs/designers-developers/developers/filters/autocomplete-filters.md": [] }
 		] },
 		{"docs/designers-developers/developers/slotfills/README.md": [
+			{ "docs/designers-developers/developers/slotfills/main-dashboard-button.md": []  },
 			{ "docs/designers-developers/developers/slotfills/plugin-block-settings-menu-item.md": []  },
 			{ "docs/designers-developers/developers/slotfills/plugin-document-setting-panel.md": []  },
 			{ "docs/designers-developers/developers/slotfills/plugin-more-menu-item.md": []  },

lib/block-supports/typography.php

@@ -15,12 +15,19 @@ function gutenberg_register_typography_support( $block_type ) {
 		return;
 	}
 
-	$has_font_appearance_support = gutenberg_experimental_get( $block_type->supports, array( '__experimentalFontAppearance' ), false );
 	$has_font_size_support       = gutenberg_experimental_get( $block_type->supports, array( 'fontSize' ), false );
+	$has_font_style_support      = gutenberg_experimental_get( $block_type->supports, array( '__experimentalFontStyle' ), false );
+	$has_font_weight_support     = gutenberg_experimental_get( $block_type->supports, array( '__experimentalFontWeight' ), false );
 	$has_line_height_support     = gutenberg_experimental_get( $block_type->supports, array( 'lineHeight' ), false );
 	$has_text_decoration_support = gutenberg_experimental_get( $block_type->supports, array( '__experimentalTextDecoration' ), false );
 	$has_text_transform_support  = gutenberg_experimental_get( $block_type->supports, array( '__experimentalTextTransform' ), false );
-	$has_typography_support      = $has_font_appearance_support || $has_font_size_support || $has_line_height_support || $has_text_transform_support || $has_text_decoration_support;
+
+	$has_typography_support = $has_font_size_support
+		|| $has_font_weight_support
+		|| $has_font_style_support
+		|| $has_line_height_support
+		|| $has_text_transform_support
+		|| $has_text_decoration_support;
 
 	if ( ! $block_type->attributes ) {
 		$block_type->attributes = array();
@@ -57,8 +64,9 @@ function gutenberg_apply_typography_support( $block_type, $block_attributes ) {
 	$classes = array();
 	$styles  = array();
 
-	$has_font_appearance_support = gutenberg_experimental_get( $block_type->supports, array( '__experimentalFontAppearance' ), false );
 	$has_font_family_support     = gutenberg_experimental_get( $block_type->supports, array( '__experimentalFontFamily' ), false );
+	$has_font_style_support      = gutenberg_experimental_get( $block_type->supports, array( '__experimentalFontStyle' ), false );
+	$has_font_weight_support     = gutenberg_experimental_get( $block_type->supports, array( '__experimentalFontWeight' ), false );
 	$has_font_size_support       = gutenberg_experimental_get( $block_type->supports, array( 'fontSize' ), false );
 	$has_line_height_support     = gutenberg_experimental_get( $block_type->supports, array( 'lineHeight' ), false );
 	$has_text_decoration_support = gutenberg_experimental_get( $block_type->supports, array( '__experimentalTextDecoration' ), false );
@@ -94,14 +102,17 @@ function gutenberg_apply_typography_support( $block_type, $block_attributes ) {
 		}
 	}
 
-	// Font appearance - style and weight.
-	if ( $has_font_appearance_support ) {
+	// Font style.
+	if ( $has_font_style_support ) {
 		// Apply font style.
 		$font_style = gutenberg_typography_get_css_variable_inline_style( $block_attributes, 'fontStyle', 'font-style' );
 		if ( $font_style ) {
 			$styles[] = $font_style;
 		}
+	}
 
+	// Font weight.
+	if ( $has_font_weight_support ) {
 		// Apply font weight.
 		$font_weight = gutenberg_typography_get_css_variable_inline_style( $block_attributes, 'fontWeight', 'font-weight' );
 		if ( $font_weight ) {