Issue #3277311 by nod_, Wim Leers, catch, larowlan: Deprecate and mark internal contextual JS API

core/modules/contextual/js/contextual.es6.js

@@ -132,11 +132,19 @@
     contextual.collection.add(model);
 
     // Let other JavaScript react to the adding of a new contextual link.
-    $(document).trigger('drupalContextualLinkAdded', {
-      $el: $contextual,
-      $region,
-      model,
-    });
+    $(document).trigger(
+      'drupalContextualLinkAdded',
+      Drupal.deprecatedProperty({
+        target: {
+          $el: $contextual,
+          $region,
+          model,
+        },
+        deprecatedProperty: 'model',
+        message:
+          'The model property is deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no replacement.',
+      }),
+    );
 
     // Fix visual collisions between contextual link triggers.
     adjustIfNestedAndOverlapping($contextual);
@@ -240,6 +248,8 @@
    * Namespace for contextual related functionality.
    *
    * @namespace
+   *
+   * @private
    */
   Drupal.contextual = {
     /**
@@ -247,6 +257,9 @@
      * element of contextual links.
      *
      * @type {Array}
+     *
+     * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+     *  replacement.
      */
     views: [],
 
@@ -255,6 +268,9 @@
      * contextual region element.
      *
      * @type {Array}
+     *
+     * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+     *  replacement.
      */
     regionViews: [],
   };
@@ -263,6 +279,9 @@
    * A Backbone.Collection of {@link Drupal.contextual.StateModel} instances.
    *
    * @type {Backbone.Collection}
+   *
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
    */
   Drupal.contextual.collection = new Backbone.Collection([], {
     model: Drupal.contextual.StateModel,

core/modules/contextual/js/contextual.js

@@ -84,11 +84,15 @@
       model: model
     }, options)));
     contextual.collection.add(model);
-    $(document).trigger('drupalContextualLinkAdded', {
-      $el: $contextual,
-      $region: $region,
-      model: model
-    });
+    $(document).trigger('drupalContextualLinkAdded', Drupal.deprecatedProperty({
+      target: {
+        $el: $contextual,
+        $region: $region,
+        model: model
+      },
+      deprecatedProperty: 'model',
+      message: 'The model property is deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no replacement.'
+    }));
     adjustIfNestedAndOverlapping($contextual);
   }
 

core/modules/contextual/js/contextual.toolbar.es6.js

@@ -69,12 +69,17 @@
    * Namespace for the contextual toolbar.
    *
    * @namespace
+   *
+   * @private
    */
   Drupal.contextualToolbar = {
     /**
      * The {@link Drupal.contextualToolbar.StateModel} instance.
      *
      * @type {?Drupal.contextualToolbar.StateModel}
+     *
+     * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is
+     * no replacement.
      */
     model: null,
   };

core/modules/contextual/js/models/StateModel.es6.js

@@ -10,6 +10,9 @@
    * @constructor
    *
    * @augments Backbone.Model
+   *
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
    */
   Drupal.contextual.StateModel = Backbone.Model.extend(
     /** @lends Drupal.contextual.StateModel# */ {

core/modules/contextual/js/toolbar/models/StateModel.es6.js

@@ -4,6 +4,10 @@
  */
 
 (function (Drupal, Backbone) {
+  /**
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
+   */
   Drupal.contextualToolbar.StateModel = Backbone.Model.extend(
     /** @lends Drupal.contextualToolbar.StateModel# */ {
       /**

core/modules/contextual/js/toolbar/views/AuralView.es6.js

@@ -4,6 +4,10 @@
  */
 
 (function ($, Drupal, Backbone, _) {
+  /**
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
+   */
   Drupal.contextualToolbar.AuralView = Backbone.View.extend(
     /** @lends Drupal.contextualToolbar.AuralView# */ {
       /**

core/modules/contextual/js/toolbar/views/VisualView.es6.js

@@ -4,6 +4,10 @@
  */
 
 (function (Drupal, Backbone) {
+  /**
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
+   */
   Drupal.contextualToolbar.VisualView = Backbone.View.extend(
     /** @lends Drupal.contextualToolbar.VisualView# */ {
       /**

core/modules/contextual/js/views/AuralView.es6.js

@@ -4,6 +4,10 @@
  */
 
 (function (Drupal, Backbone) {
+  /**
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
+   */
   Drupal.contextual.AuralView = Backbone.View.extend(
     /** @lends Drupal.contextual.AuralView# */ {
       /**

core/modules/contextual/js/views/KeyboardView.es6.js

@@ -4,6 +4,10 @@
  */
 
 (function (Drupal, Backbone) {
+  /**
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
+   */
   Drupal.contextual.KeyboardView = Backbone.View.extend(
     /** @lends Drupal.contextual.KeyboardView# */ {
       /**

core/modules/contextual/js/views/RegionView.es6.js

@@ -4,6 +4,10 @@
  */
 
 (function (Drupal, Backbone) {
+  /**
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
+   */
   Drupal.contextual.RegionView = Backbone.View.extend(
     /** @lends Drupal.contextual.RegionView# */ {
       /**

core/modules/contextual/js/views/VisualView.es6.js

@@ -4,6 +4,10 @@
  */
 
 (function (Drupal, Backbone) {
+  /**
+   * @deprecated in drupal:9.4.0 and is removed from drupal:10.0.0. There is no
+   *  replacement.
+   */
   Drupal.contextual.VisualView = Backbone.View.extend(
     /** @lends Drupal.contextual.VisualView# */ {
       /**

core/modules/contextual/src/ContextualController.php

@@ -57,6 +57,8 @@ public static function create(ContainerInterface $container) {
    * @throws \Symfony\Component\HttpKernel\Exception\BadRequestHttpException
    *   Thrown when the request contains no ids.
    *
+   * @internal
+   *
    * @see contextual_preprocess()
    */
   public function render(Request $request) {