core/modules/outside_in/outside_in.api.php         |  63 ++++++++++++
 core/modules/outside_in/outside_in.module          |   9 +-
 .../outside_in_test/outside_in_test.info.yml       |   9 ++
 .../OffCanvasFormAnntationIsClassBlockForm.php     |  44 +++++++++
 .../Block/OffCanvasFormAnnotationIsClassBlock.php  |  27 +++++
 .../Block/OffCanvasFormAnnotationIsFalseBlock.php  |  27 +++++
 .../Block/OffCanvasFormAnnotationNoneBlock.php     |  24 +++++
 .../tests/src/Functional/OutsideInTest.php         | 110 +++++++++++++++++++++
 .../OutsideInBlockFormTest.php                     |  23 +++++
 9 files changed, 335 insertions(+), 1 deletion(-)

diff --git a/core/modules/outside_in/outside_in.api.php b/core/modules/outside_in/outside_in.api.php
new file mode 100644
index 0000000..2f9439f
--- /dev/null
+++ b/core/modules/outside_in/outside_in.api.php
@@ -0,0 +1,63 @@
+<?php
+
+/**
+ * @file
+ * Documentation for Settings Tray API.
+ */
+
+/**
+ * @defgroup outside_in Settings Tray API
+ * @{
+ * Settings Tray API
+ *
+ * @section sec_overview Overview and terminology
+ *
+ * The goal of the Settings Tray module is to make administering blocks easier,
+ * and therefore to make the site building experience faster and more pleasant.
+ *
+ * It achieves this by building on the infrastructure that the Contextual
+ * Links module provides: Settings Tray provides a "Quick Edit" contextual link
+ * for blocks. Clicking this contextual link opens the Settings Tray, which
+ * allows to change the contents of the block (not the visibility conditions).
+ * This means blocks can be modified without leaving the page.
+ *
+ * The Settings Tray uses a variant of a standard dialog: an off-canvas dialog.
+ *
+ * @section sec_api The API: the form in the Settings Tray
+ *
+ * By default, every block will show their built-in form in the Settings Tray.
+ * However, many blocks would benefit from a tailored form which limits the form
+ * to only the form items that affect the content of the rendered block: this
+ * results in a better experience.
+ *
+ * Each block plugin can specify which form to use in the off-canvas dialog:
+ * @code
+ * forms = {
+ *   "off_canvas" = "\Drupal\some_module\Form\MyBlockOffCanvasForm",
+ * },
+ * @encode
+ *
+ * In rare cases, a block's content cannot be modified — for example the page
+ * title, main content and help blocks. In these cases, you can opt-out:
+ * @code
+ * forms = {
+ *   "off_canvas" = FALSE,
+ * },
+ * @encode
+ *
+ * Finally, blocks that do not provide "off-canvas forms" will automatically
+ * have it set to their plugin class. For example, the "Powered by Drupal" block
+ * plugin (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets
+ * this added to its annotation:
+ * @code
+ * forms = {
+ *   "off_canvas" = "\Drupal\system\Plugin\Block\SystemPoweredByBlock",
+ * },
+ * @encode
+ *
+ * Therefore, the entire Settings Tray API is just this annotation: it controls
+ * what the Settings Tray does for a given block.
+ *
+ * @see outside_in_block_alter
+ * @see \Drupal\Tests\outside_in\Functional\OutsideInBlockTest::testPossibleAnnotations()
+ */
diff --git a/core/modules/outside_in/outside_in.module b/core/modules/outside_in/outside_in.module
index 665468a..92bcd94 100644
--- a/core/modules/outside_in/outside_in.module
+++ b/core/modules/outside_in/outside_in.module
@@ -162,7 +162,7 @@ function outside_in_block_alter(&$definitions) {
 
     switch ($definition['id']) {
       // Use specialized off-canvas forms when they're available.
-      // @todo move these into the corresponding block plugin annotations when Settings Tray becomes stable.
+      // @todo move these into the corresponding block plugin annotations in https://www.drupal.org/node/2896356
       case 'system_menu_block':
         $definition['forms']['off_canvas'] = SystemMenuOffCanvasForm::class;
         break;
@@ -173,9 +173,16 @@ function outside_in_block_alter(&$definitions) {
       // No off-canvas form for the page title block, despite it having
       // contextual links: it's too confusing that you're editing configuration,
       // not content, so the title itself cannot actually be changed.
+      // @todo move these into the corresponding block plugin annotations in https://www.drupal.org/node/2896356
       case 'page_title_block':
         $definition['forms']['off_canvas'] = FALSE;
         break;
+      case 'system_main_block':
+        $definition['forms']['off_canvas'] = FALSE;
+        break;
+      case 'help_block':
+        $definition['forms']['off_canvas'] = FALSE;
+        break;
 
       // Otherwise fall back to the built-in form for the block plugin.
       default:
diff --git a/core/modules/outside_in/tests/modules/outside_in_test/outside_in_test.info.yml b/core/modules/outside_in/tests/modules/outside_in_test/outside_in_test.info.yml
new file mode 100644
index 0000000..590f559
--- /dev/null
+++ b/core/modules/outside_in/tests/modules/outside_in_test/outside_in_test.info.yml
@@ -0,0 +1,9 @@
+name: 'Settings Tray Test'
+type: module
+description: 'Provides Settings Tray test functionality.'
+package: Testing
+version: VERSION
+core: 8.x
+dependencies:
+  - block
+  - outside_in
diff --git a/core/modules/outside_in/tests/modules/outside_in_test/src/Form/OffCanvasFormAnntationIsClassBlockForm.php b/core/modules/outside_in/tests/modules/outside_in_test/src/Form/OffCanvasFormAnntationIsClassBlockForm.php
new file mode 100644
index 0000000..2136615
--- /dev/null
+++ b/core/modules/outside_in/tests/modules/outside_in_test/src/Form/OffCanvasFormAnntationIsClassBlockForm.php
@@ -0,0 +1,44 @@
+<?php
+
+namespace Drupal\outside_in_test\Form;
+
+use Drupal\Core\Form\FormStateInterface;
+use Drupal\Core\Plugin\PluginFormBase;
+
+/**
+ * @see \Drupal\outside_in_test\Plugin\Block\OffCanvasFormAnnotationIsClassBlock
+ */
+class OffCanvasFormAnntationIsClassBlockForm extends PluginFormBase {
+
+  /**
+   * The block plugin.
+   *
+   * @var \Drupal\Core\Block\BlockPluginInterface
+   */
+  protected $plugin;
+
+  /**
+   * {@inheritdoc}
+   */
+  public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
+    $form = $this->plugin->buildConfigurationForm($form, $form_state);
+
+    $form['some_setting'] = [
+      '#type' => 'select',
+      '#title' => t('Some setting'),
+      '#options' => [
+        'a' => 'A',
+        'b' => 'B',
+      ],
+      '#required' => TRUE,
+    ];
+
+    return $form;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {}
+
+}
diff --git a/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsClassBlock.php b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsClassBlock.php
new file mode 100644
index 0000000..41af9dc
--- /dev/null
+++ b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsClassBlock.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Drupal\outside_in_test\Plugin\Block;
+
+use Drupal\Core\Block\BlockBase;
+
+/**
+ * Block that explicitly provides an "off_canvas" form class.
+ *
+ * @Block(
+ *   id = "outside_in_test_class",
+ *   admin_label = "Settings Tray test block: forms[off_canvas]=class",
+ *   forms = {
+ *     "off_canvas" = "\Drupal\outside_in_test\Form\OffCanvasFormAnntationIsClassBlockForm",
+ *   },
+ * )
+ */
+class OffCanvasFormAnnotationIsClassBlock extends BlockBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function build() {
+    return ['#markup' => '<span>class</span>'];
+  }
+
+}
diff --git a/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsFalseBlock.php b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsFalseBlock.php
new file mode 100644
index 0000000..6458fa1
--- /dev/null
+++ b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsFalseBlock.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Drupal\outside_in_test\Plugin\Block;
+
+use Drupal\Core\Block\BlockBase;
+
+/**
+ * Block that explicitly provides no "off_canvas" form, thus opting out.
+ *
+ * @Block(
+ *   id = "outside_in_test_false",
+ *   admin_label = "Settings Tray test block: forms[off_canvas]=FALSE",
+ *   forms = {
+ *     "off_canvas" = FALSE,
+ *   },
+ * )
+ */
+class OffCanvasFormAnnotationIsFalseBlock extends BlockBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function build() {
+    return ['#markup' => '<span>FALSE</span>'];
+  }
+
+}
diff --git a/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationNoneBlock.php b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationNoneBlock.php
new file mode 100644
index 0000000..1e67f23
--- /dev/null
+++ b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationNoneBlock.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace Drupal\outside_in_test\Plugin\Block;
+
+use Drupal\Core\Block\BlockBase;
+
+/**
+ * Block that does nothing explicit for Settings Tray.
+ *
+ * @Block(
+ *   id = "outside_in_test_none",
+ *   admin_label = "Settings Tray test block: forms[off_canvas] is not specified",
+ * )
+ */
+class OffCanvasFormAnnotationNoneBlock extends BlockBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function build() {
+    return ['#markup' => '<span>none</span>'];
+  }
+
+}
diff --git a/core/modules/outside_in/tests/src/Functional/OutsideInTest.php b/core/modules/outside_in/tests/src/Functional/OutsideInTest.php
new file mode 100644
index 0000000..3a009bb
--- /dev/null
+++ b/core/modules/outside_in/tests/src/Functional/OutsideInTest.php
@@ -0,0 +1,110 @@
+<?php
+
+namespace Drupal\Tests\outside_in\Functional;
+
+use Drupal\block\Entity\Block;
+use Drupal\block_content\Entity\BlockContent;
+use Drupal\block_content\Entity\BlockContentType;
+use Drupal\Tests\BrowserTestBase;
+use Drupal\user\Entity\Role;
+
+/**
+ * Testing opening and saving block forms in the off-canvas dialog.
+ *
+ * @group outside_in
+ */
+class OutsideInBlockTest extends BrowserTestBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  public static $modules = [
+    'outside_in',
+    'outside_in_test',
+  ];
+
+  /**
+   * Gets the block CSS selector.
+   *
+   * @param \Drupal\block\Entity\Block $block
+   *   The block.
+   *
+   * @return string
+   *   The CSS selector.
+   */
+  protected  function getBlockSelector(Block $block) {
+    return '#block-' . $block->id();
+  }
+
+  /**
+   * Tests the three possible forms[off_canvas] annotations: class, FALSE, none.
+   *
+   * There is also functional JS test coverage to ensure that the two blocks
+   * that support Settings Tray (the "class" & "none" cases) do work correctly.
+   *
+   * @see OutsideInBlockFormTest::testBlocks()
+   */
+  public function testPossibleAnnotations() {
+    $test_block_plugin_ids = [
+      // Block that explicitly provides an "off_canvas" form class.
+      'outside_in_test_class',
+      // Block that explicitly provides no "off_canvas" form, thus opting out.
+      'outside_in_test_false',
+      // Block that does nothing explicit for Settings Tray.
+      'outside_in_test_none',
+    ];
+
+    $placed_blocks = [];
+    foreach ($test_block_plugin_ids as $plugin_id) {
+      $placed_blocks[$plugin_id] = $this->placeBlock($plugin_id);
+    }
+
+    $this->drupalGet('');
+    $web_assert = $this->assertSession();
+    foreach ($placed_blocks as $plugin_id => $placed_block) {
+      $block_selector = $this->getBlockSelector($placed_block);
+
+      // All blocks are rendered.
+      $web_assert->elementExists('css', $block_selector);
+
+      // All blocks except 'outside_in_test_false' are editable. For more
+      // detailed test coverage, which requires JS execution, see
+      // OutsideInBlockFormTest::testBlocks().
+      if ($plugin_id !== 'outside_in_test_false') {
+        $web_assert->elementExists('css', "{$block_selector}[data-drupal-outsidein=\"editable\"]");
+      }
+      else {
+        $web_assert->elementNotExists('css', "{$block_selector}[data-drupal-outsidein=\"editable\"]");
+      }
+    }
+  }
+
+  /**
+   * Tests that certain blocks opt out from Settings Tray.
+   */
+  public function testOptOut() {
+    $web_assert = $this->assertSession();
+
+    $non_excluded_block = $this->placeBlock('system_powered_by_block');
+    $excluded_block_plugin_ids = ['page_title_block', 'system_main_block', 'outside_in_test_false'];
+    $block_selectors = [];
+    // Place blocks that should be excluded.
+    foreach ($excluded_block_plugin_ids as $excluded_block_plugin_id) {
+      // The block HTML 'id' attribute will be "block-[block_id]".
+      $block_selectors[] = $this->getBlockSelector($this->placeBlock($excluded_block_plugin_id));
+    }
+    $this->drupalGet('');
+    // Assert that block has been marked as "editable" and contextual that
+    // should exist does.
+    $web_assert->elementExists('css', $this->getBlockSelector($non_excluded_block) . "[data-drupal-outsidein=\"editable\"]");
+    // Assert that each block that has a "forms[off_canvas] = FALSE" annotation:
+    // - is still rendered on the page
+    // - but is not marked as "editable" by outside_in_preprocess_block()
+    // - and does not have the Settings Tray contextual link
+    foreach ($block_selectors as $block_selector) {
+      $web_assert->elementExists('css', $block_selector);
+      $web_assert->elementNotExists('css', "{$block_selector}[data-drupal-outsidein=\"editable\"]");
+      $web_assert->elementNotExists('css', "$block_selector [data-outside-in-edit]");
+    }
+  }
+}
diff --git a/core/modules/outside_in/tests/src/FunctionalJavascript/OutsideInBlockFormTest.php b/core/modules/outside_in/tests/src/FunctionalJavascript/OutsideInBlockFormTest.php
index 04fc230..4353355 100644
--- a/core/modules/outside_in/tests/src/FunctionalJavascript/OutsideInBlockFormTest.php
+++ b/core/modules/outside_in/tests/src/FunctionalJavascript/OutsideInBlockFormTest.php
@@ -35,6 +35,7 @@ class OutsideInBlockFormTest extends OutsideInJavascriptTestBase {
     // Add test module to override CSS pointer-events properties because they
     // cause test failures.
     'outside_in_test_css',
+    'outside_in_test',
   ];
 
   /**
@@ -109,6 +110,10 @@ public function testBlocks($block_plugin, $new_page_text, $element_selector, $la
           // Fill out form, save the form.
           $page->fillField('settings[site_information][site_name]', $new_page_text);
           break;
+
+        case 'outside_in_test_class':
+          $web_assert->elementExists('css', '[data-drupal-selector="edit-settings-some-setting"]');
+          break;
       }
 
       if (isset($new_page_text)) {
@@ -176,6 +181,24 @@ public function providerTestBlocks() {
         'button_text' => 'Save Search form',
         'toolbar_item' => NULL,
       ],
+      // This is the functional JS test coverage accompanying testPossibleAnnotations().
+      '\Drupal\outside_in_test\Plugin\Block\OffCanvasFormAnnotationIsClassBlock' => [
+        'block_plugin' => 'outside_in_test_class',
+        'new_page_text' => NULL,
+        'element_selector' => 'span',
+        'label_selector' => 'h2',
+        'button_text' => 'Save Settings Tray test block: forms[off_canvas]=class',
+        'toolbar_item' => NULL,
+      ],
+      // This is the functional JS test coverage accompanying testPossibleAnnotations().
+      '\Drupal\outside_in_test\Plugin\Block\OffCanvasFormAnnotationNoneBlock' => [
+        'block_plugin' => 'outside_in_test_none',
+        'new_page_text' => NULL,
+        'element_selector' => 'span',
+        'label_selector' => 'h2',
+        'button_text' => 'Save Settings Tray test block: forms[off_canvas] is not specified',
+        'toolbar_item' => NULL,
+      ],
     ];
     return $blocks;
   }