Support adding opt-in visual styles for core blocks

core-blocks/separator/index.js

@@ -8,6 +8,7 @@ import { createBlock } from '@wordpress/blocks';
  * Internal dependencies
  */
 import './style.scss';
+import './theme.scss';
 
 export const name = 'core/separator';
 

core-blocks/separator/theme.scss

@@ -0,0 +1,2 @@
+// TODO: Remove this comment when adding theme styles.
+// Including an empty file for now so webpack will build an aggregate build/core-blocks/theme.css.

docs/extensibility/theme-support.md

@@ -151,3 +151,11 @@ body.gutenberg-editor-page .editor-block-list__block[data-align="full"] {
 You can use those editor widths to match those in your theme. You can use any CSS width unit, including `%` or `px`.
 
 Further reading: [Applying Styles with Stylesheets](https://wordpress.org/gutenberg/handbook/blocks/applying-styles-with-stylesheets/).
+
+## Default block styles
+
+Core blocks include default styles. The styles are enqueued for editing but are not enqueued for viewing unless the theme opts-in to the core styles. If you'd like to use default styles in your theme, add theme support for `wp-block-styles`:
+
+```php
+add_theme_support( 'wp-block-styles' );
+```

lib/client-assets.php

@@ -426,19 +426,32 @@ function gutenberg_register_scripts_and_styles() {
 	wp_register_style(
 		'wp-core-blocks',
 		gutenberg_url( 'build/core-blocks/style.css' ),
-		array(),
+		current_theme_supports( 'wp-block-styles' ) ? array( 'wp-core-blocks-theme' ) : array(),
 		filemtime( gutenberg_dir_path() . 'build/core-blocks/style.css' )
 	);
 	wp_style_add_data( 'wp-core-blocks', 'rtl', 'replace' );
 
 	wp_register_style(
 		'wp-edit-blocks',
 		gutenberg_url( 'build/core-blocks/edit-blocks.css' ),
-		array( 'wp-components', 'wp-editor' ),
+		array(
+			'wp-components',
+			'wp-editor',
+			// Always include visual styles so the editor never appears broken.
+			'wp-core-blocks-theme',
+		),
 		filemtime( gutenberg_dir_path() . 'build/core-blocks/edit-blocks.css' )
 	);
 	wp_style_add_data( 'wp-edit-blocks', 'rtl', 'replace' );
 
+	wp_register_style(
+		'wp-core-blocks-theme',
+		gutenberg_url( 'build/core-blocks/theme.css' ),
+		array(),
+		filemtime( gutenberg_dir_path() . 'build/core-blocks/theme.css' )
+	);
+	wp_style_add_data( 'wp-core-blocks-theme', 'rtl', 'replace' );
+
 	wp_register_script(
 		'wp-plugins',
 		gutenberg_url( 'build/plugins/index.js' ),

phpunit/class-core-block-theme-test.php

@@ -0,0 +1,106 @@
+<?php
+/**
+ * Core block theme tests.
+ *
+ * @package Gutenberg
+ */
+
+/**
+ * Test inclusion of opt-in core block theme.
+ */
+class Core_Block_Theme_Test extends WP_UnitTestCase {
+	private $old_wp_styles;
+	private $old_wp_scripts;
+
+	function setUp() {
+		parent::setUp();
+
+		$this->old_wp_scripts = isset( $GLOBALS['wp_scripts'] ) ? $GLOBALS['wp_scripts'] : null;
+		remove_action( 'wp_default_scripts', 'wp_default_scripts' );
+
+		$GLOBALS['wp_scripts']                  = new WP_Scripts();
+		$GLOBALS['wp_scripts']->default_version = get_bloginfo( 'version' );
+
+		$this->old_wp_styles = isset( $GLOBALS['wp_styles'] ) ? $GLOBALS['wp_styles'] : null;
+		remove_action( 'wp_default_styles', 'wp_default_styles' );
+
+		$GLOBALS['wp_styles']                  = new WP_Styles();
+		$GLOBALS['wp_styles']->default_version = get_bloginfo( 'version' );
+	}
+
+	function tearDown() {
+		$GLOBALS['wp_scripts'] = $this->old_wp_scripts;
+		add_action( 'wp_default_scripts', 'wp_default_scripts' );
+
+		$GLOBALS['wp_styles'] = $this->old_wp_styles;
+		add_action( 'wp_default_styles', 'wp_default_styles' );
+
+		if ( current_theme_supports( 'wp-block-styles' ) ) {
+			remove_theme_support( 'wp-block-styles' );
+		}
+
+		parent::tearDown();
+	}
+
+	/**
+	 * Tests that visual block styles are enqueued in the editor even when there is not theme support for 'wp-block-styles'.
+	 *
+	 * Visual block styles should always be enqueued when editing to avoid the appearance of a broken editor.
+	 */
+	function test_block_styles_for_editing_without_theme_support() {
+		// Confirm we are without theme support by default.
+		$this->assertFalse( current_theme_supports( 'wp-block-styles' ) );
+
+		gutenberg_register_scripts_and_styles();
+
+		$this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) );
+		wp_enqueue_style( 'wp-edit-blocks' );
+		$this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) );
+	}
+
+	/**
+	 * Tests that visual block styles are enqueued when there is theme support for 'wp-block-styles'.
+	 *
+	 * Visual block styles should always be enqueued when editing to avoid the appearance of a broken editor.
+	 */
+	function test_block_styles_for_editing_with_theme_support() {
+		add_theme_support( 'wp-block-styles' );
+		gutenberg_register_scripts_and_styles();
+
+		$this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) );
+		wp_enqueue_style( 'wp-edit-blocks' );
+		$this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) );
+	}
+
+	/**
+	 * Tests that visual block styles are not enqueued for viewing when there is no theme support for 'wp-block-styles'.
+	 *
+	 * Visual block styles should not be enqueued unless a theme opts in.
+	 * This way we avoid style conflicts with existing themes.
+	 */
+	function test_no_block_styles_for_viewing_without_theme_support() {
+		// Confirm we are without theme support by default.
+		$this->assertFalse( current_theme_supports( 'wp-block-styles' ) );
+
+		gutenberg_register_scripts_and_styles();
+
+		$this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) );
+		wp_enqueue_style( 'wp-core-blocks' );
+		$this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) );
+	}
+
+	/**
+	 * Tests that visual block styles are enqueued for viewing when there is theme support for 'wp-block-styles'.
+	 *
+	 * Visual block styles should be enqueued when a theme opts in.
+	 */
+	function test_block_styles_for_viewing_with_theme_support() {
+		add_theme_support( 'wp-block-styles' );
+
+		gutenberg_register_scripts_and_styles();
+
+		$this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) );
+		wp_enqueue_style( 'wp-core-blocks' );
+		$this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) );
+	}
+}

webpack.config.js

@@ -28,6 +28,11 @@ const blocksCSSPlugin = new ExtractTextPlugin( {
 	filename: './build/core-blocks/style.css',
 } );
 
+// CSS loader for default visual block styles.
+const themeBlocksCSSPlugin = new ExtractTextPlugin( {
+	filename: './build/core-blocks/theme.css',
+} );
+
 // Configuration for the ExtractTextPlugin.
 const extractConfig = {
 	use: [
@@ -237,6 +242,13 @@ const config = {
 				],
 				use: editBlocksCSSPlugin.extract( extractConfig ),
 			},
+			{
+				test: /\/theme\.s?css$/,
+				include: [
+					/core-blocks/,
+				],
+				use: themeBlocksCSSPlugin.extract( extractConfig ),
+			},
 			{
 				test: /\.s?css$/,
 				exclude: [
@@ -249,6 +261,7 @@ const config = {
 	plugins: [
 		blocksCSSPlugin,
 		editBlocksCSSPlugin,
+		themeBlocksCSSPlugin,
 		mainCSSExtractTextPlugin,
 		// Create RTL files with a -rtl suffix
 		new WebpackRTLPlugin( {