Support opt-in visual styles for core blocks

The purpose of this change is to offer default visual styles for themes
that want them without interfering with existing themes that provide
their own. Core blocks may include a `theme.scss` file containing visual
styles, and those styles will be built into
`build/core-blocks/theme.css`. The visual styles are enqueued for
editing but are not enqueued for viewing unless there is theme support
for `wp-block-styles`.

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

@@ -425,19 +425,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( {