refactor!: Update and modernize plugins for Blockly v12. (#2468)

* refactor: Update ContinuousFlyout for compatibility with new flyout API.

* chore: Rename ContinuousFlyout.js to ContinuousFlyout.ts.

* chore: Rename ContinuousToolbox.js to ContinuousToolbox.ts.

* chore: Rename ContinuousMetricsFlyout.js to ContinuousMetricsFlyout.ts.

* chore: Rename ContinuousCategory.js to ContinuousCategory.ts.

* chore: Rename ContinuousMetrics.js to ContinuousMetrics.ts.

* chore: Rename index.js to index.ts.

* refactor: Convert ContinuousToolbox to Typescript

* chore: Name RecyclableBlockFlyoutInflater.ts consistently with other files.

* refactor: Add and use a function for registering the continuous toolbox.

* chore: Improve docs.

* feat: Add support for autoclosing continuous toolboxes.

* fix: Fix bug when making configuration changes in the playground.

* refactor: Update visibility on RecyclableBlockFlyoutInflater.

* fix: Use the recycleEligibilityChecker callback if set.

* refactor: Make converting toolbox items to flyout items more extensible.

* chore: Remove debugging.

* fix: Debounce flyout refreshes.

* chore: Remove unused import.

* chore: Fix TSDoc args.

* chore: Add TSDoc for registration function.

* refactor: Clean up implementation of recordScrollPositions.

* chore: Fix TSDoc.

* chore: Remove unneeded underscores in symbol names.

* chore: Suppress unavoidable lint errors.

* fix: Fix alignment when jumping to a category.

* fix: Fix injection options and documentation.

* chore: Fix typo.

* refactor: Make the ContinuousFlyoutMetrics class and file name consistent.

* fix: Update flyout contents in response to procedure mutations.

* refactor: Make the RecyclableBlockFlyoutInflater inert for non-continuous flyouts.

* fix: Fix alignment of toolbox labels.

* chore: Update to use Blockly v12 beta.

* chore: Update plugins for compatibility with Blockly v12.

* fix: Fix tests for v12 compatibility.

* fix: Fix bug that could cause scroll jank when interrupting an animated scroll.

* chore: Revert errant test change.

* refactor: Update continuous-toolbox for latest flyout API changes.

* chore: Update Blockly dependency to 12.0.0-beta.1.

* chore: Clarify comments.

* chore: Make guard clauses single-line.

* refactor: Improve typings for getViewMetrics().

* fix: Fix missing return.

* chore: Add comment clarifying FlyoutButton weirdness.

* chore: Improve formatting.

* refactor: Use direct field access instead of pass-through setters.

* fix: Check for modern mutations when determining block recyclability.

* chore: Add comment clarifying flyout positioning checks.

* fix: Remove explicit public visibility annotations.

* fix: Don't recycle blocks with any mutation-related methods.

* chore: Add some information about block recycling to the README.

* chore: Improve continuous toolbox README.

Author: gonfunko

package-lock.json

@@ -36,7 +36,7 @@
     "@eslint/js": "^8.49.0",
     "@typescript-eslint/eslint-plugin": "^6.7.2",
     "@typescript-eslint/parser": "^6.7.2",
-    "blockly": "^11.0.0",
+    "blockly": "^12.0.0-beta.1",
     "conventional-changelog-conventionalcommits": "^5.0.0",
     "eslint": "^8.49.0",
     "eslint-config-google": "^0.14.0",

package.json

@@ -13,7 +13,7 @@ export class ObservableParameterModel
   implements Blockly.procedures.IParameterModel
 {
   private id: string;
-  private variable: Blockly.VariableModel;
+  private variable: Blockly.IVariableModel<Blockly.IVariableState>;
   private shouldFireEvents = false;
   private procedureModel: Blockly.procedures.IProcedureModel | null = null;
 
@@ -44,8 +44,8 @@ export class ObservableParameterModel
    * @returns This parameter model.
    */
   setName(name: string, id?: string): this {
-    if (name === this.variable.name) return this;
-    const oldName = this.variable.name;
+    if (name === this.variable.getName()) return this;
+    const oldName = this.variable.getName();
     this.variable =
       this.workspace.getVariable(name) ??
       this.workspace.createVariable(name, '', id);
@@ -73,7 +73,7 @@ export class ObservableParameterModel
   protected createBackingVariable(
     name: string,
     varId?: string,
-  ): Blockly.VariableModel {
+  ): Blockly.IVariableModel<Blockly.IVariableState> {
     this.variable =
       this.workspace.getVariable(name) ??
       this.workspace.createVariable(name, '', varId);
@@ -100,7 +100,7 @@ export class ObservableParameterModel
    * @returns the name of this parameter.
    */
   getName(): string {
-    return this.variable.name;
+    return this.variable.getName();
   }
 
   /**
@@ -123,7 +123,7 @@ export class ObservableParameterModel
   /**
    * @returns the variable model associated with the parameter model.
    */
-  getVariableModel(): Blockly.VariableModel {
+  getVariableModel(): Blockly.IVariableModel<Blockly.IVariableState> {
     return this.variable;
   }
 

plugins/block-shareable-procedures/src/observable_parameter_model.ts

@@ -1237,6 +1237,7 @@ suite('Procedures', function () {
       'if a procedure caller block was already disabled before ' +
         'its definition was disabled, it is not reenabled',
       function () {
+        this.workspace.options.disable = true;
         const defBlock = createProcDefBlock(this.workspace);
         const callBlock = createProcCallBlock(this.workspace);
         globalThis.clock.runAll();

plugins/block-shareable-procedures/test/procedure_blocks.mocha.js

@@ -13,7 +13,7 @@ import * as Blockly from 'blockly/core';
 /**
  * List of events that cause a change in content area size.
  */
-const contentChangeEvents = [
+const contentChangeEvents: string[] = [
   Blockly.Events.VIEWPORT_CHANGE,
   Blockly.Events.BLOCK_MOVE,
   Blockly.Events.BLOCK_DELETE,

plugins/content-highlight/src/index.ts

@@ -21,30 +21,50 @@ npm install @blockly/continuous-toolbox --save
 
 ## Usage
 
-Include the toolbox, flyout, and metrics manager classes from the plugin in the options struct used when injecting Blockly. This style of flyout works best with a toolbox definition that does not use collapsible categories.
+Import and call the `registerContinuousToolbox()` function before injecting
+Blockly. This style of flyout works best with a toolbox definition that does
+not use collapsible categories.
 
-Note that this plugin uses APIs introduced in the `3.20200924.3` release of Blockly, so you will need to use at least this version or higher.
+Note that this plugin uses APIs introduced in the `v12` release of Blockly, so
+you will need to use at least this version or higher.
 
 ```js
 import * as Blockly from 'blockly';
-import {
-  ContinuousToolbox,
-  ContinuousFlyout,
-  ContinuousMetrics,
-} from '@blockly/continuous-toolbox';
+import {registerContinuousToolbox} from '@blockly/continuous-toolbox';
 
 // Inject Blockly.
+registerContinuousToolbox();
 const workspace = Blockly.inject('blocklyDiv', {
+  toolbox: toolboxCategories,
   plugins: {
-    toolbox: ContinuousToolbox,
-    flyoutsVerticalToolbox: ContinuousFlyout,
-    metricsManager: ContinuousMetrics,
+    flyoutsVerticalToolbox: 'ContinuousFlyout',
+    metricsManager: 'ContinuousMetrics',
+    toolbox: 'ContinuousToolbox',
   },
-  toolbox: toolboxCategories,
   // ... your other options here ...
 });
 ```
 
+## Block Recycling
+
+As a performance optimization, by default the continuous toolbox "recycles"
+blocks to avoid having to create DOM elements for potentially hundreds of blocks
+every time the flyout is shown. With the default set of blocks, this drops the
+time to show the flyout from roughly 35ms to 25ms; the effect is naturally
+larger with larger block sets.
+
+Recycling is unrelated to Blockly's Trash feature; instead, it entails moving
+the blocks offscreen when the flyout is hidden, and then simply repositioning
+them when the flyout is shown again. Not all block types are amenable to this;
+in particular, blocks with dynamic behavior (e.g. those that reference
+variables, support mutations, or have dynamic dropdown fields) are excluded by
+default.
+
+This feature can be toggled by calling `setRecyclingEnabled()` on an instance of
+`ContinuousFlyout`, and the default ruleset for determining which blocks are
+safe for recycling can be replaced with a custom callback by passing that
+function to `setBlockIsRecyclable()`.
+
 ## License
 
 Apache 2.0