feat!: add block definitions to fields (google#2299)

* feat!: add block definitions to colour field plugin (google#2162)

* feat: export functions to register some angle, colour, and multiline input fields

* feat: add block definitions to colour and multiline input fields

* feat: add block generators for the colour_picker block

* fix: use Blockly.common.defineBlocksWithJsonArray

* feat: add block generators for colour_random block

* feat: add generators type and standardize exports for block files

* chore: update to blockly@beta and fix types

* chore: move all colour blocks to separate files and add more generator-related types

* feat: finish adding block code generators for colour blocks

* fix: PR feedback

* fix: remove immediate registration of blocks and fields in field_colour

* chore: use named imports and numbered TODOs

* feat: add usage information about blocks to README

* chore: revert changes outside of field_colour

* chore: clean up tsdoc and exports

* cgire: clean up README

* chore: respond to PR feedback on names and comments

* feat(tests): add and improve tests

* chore(format): run formatter

* fix: respond to PR feedback about names and file structure

* fix: allow const variables to have UPPER_CASE names

* fix: respond to PR feedback

* chore: format

* fix: line length

* feat!: add block definition to multiline text field plugin (google#2202)

* chore: force-install blockly 10.4.0-beta.1 for development

* feat: add text_multiline block and associated generators

* feat: update test page to use new block and field

* feat: README

* chore: respond to PR feedback

BREAKING CHANGE: The multiline text input field no longer registers itself on load. The developer must either manually register the field or install blocks, which will install the field. This is part of a move to have no side effects in field and block definitions, so that tree-shaking can remove unwanted fields and blocks.

* chore: format (google#2221)

* feat!: Add registration function to field_angle and make it no longer install on file load (google#2211)

* feat!: Add registration function to field_angle and make it no longer install on file load

* chore: formatting

BREAKING CHANGE: The angle field no longer registers itself on load. The developer must manually register the field. This is part of a move to have no side effects in field and block definitions, so that tree-shaking can remove unwanted fields and blocks.

* feat: add tests for per-block generators in field-colour (google#2220)

* feat: add unit tests for generators

* fix: imports in tests

* chore: format

* feat: ignore golden files in plugin tests

* chore: fix lint

* feat: ignore golden files for linting

* fix: revert addition of fs and path packages

* fix: remove suite.only to make all tests run

* chore: handle review feedback

* fix: only import what you need in colour blocks

* feat: add generator tests for the text_multiline block (google#2232)

* feat: add generator tests for the text_multiline block

* fix: updated test string to include multiple types of quotes

* fix: code style in generators for field colour blocks (google#2233)

* feat!: update blockly version to 10.4.3 for colour and multilineinput (google#2296)

* feat!: update blockly version to 10.4.3 for colour and multilineinput

* chore!: update peer dependencies

* chore: update package-lock.jsons

* chore: fix dependencies

.prettierignore

@@ -21,3 +21,5 @@ PULL_REQUEST_TEMPLATE.md
 plugins/dev-create/templates/sample-app/*
 plugins/dev-create/templates/sample-app-ts/*
 
+# Golden test files
+plugins/**/golden/*

eslint.config.js

@@ -44,6 +44,8 @@ module.exports = [
       // specific examples that are sometimes copied into plugins
       'plugins/dev-create/templates/sample-app',
       'plugins/dev-create/templates/sample-app-ts',
+      // Golden test files
+      'plugins/**/golden/*',
     ],
   },
   js.configs.recommended, // eslint-recommended

plugins/field-angle/README.md

@@ -18,6 +18,14 @@ npm install @blockly/field-angle --save
 
 ## Usage
 
+### Installation
+
+You must register this field with Blockly. You can do this by calling
+`registerFieldAngle` before instantiating your blocks. If another field is
+registered under the same name, this field will overwrite it.
+
+### Parameters
+
 This field accepts up to 9 parameters, in addition to the 4 accepted by the
 [number field][number-field]:
 
@@ -60,7 +68,9 @@ This field accepts up to 9 parameters, in addition to the 4 accepted by the
 
 ```js
 import * as Blockly from 'blockly';
-import {FieldAngle} from '@blockly/field-angle';
+import {registerFieldAngle} from '@blockly/field-angle';
+
+registerFieldAngle();
 Blockly.Blocks['test_field_angle'] = {
   init: function () {
     this.appendDummyInput()
@@ -74,7 +84,9 @@ Blockly.Blocks['test_field_angle'] = {
 
 ```js
 import * as Blockly from 'blockly';
-import '@blockly/field-angle';
+import {registerFieldAngle} from '@blockly/field-angle';
+
+registerFieldAngle();
 Blockly.defineBlocksWithJsonArray([
   {
     type: 'test_field_angle',

plugins/field-angle/src/field_angle.ts

@@ -658,12 +658,15 @@ export class FieldAngle extends Blockly.FieldNumber {
   }
 }
 
-// Unregister legacy field_angle that was in core.  Delete this once
-// core Blockly no longer defines field_angle.
-// If field_angle is not defined in core, this generates a console warning.
-Blockly.fieldRegistry.unregister('field_angle');
-
-Blockly.fieldRegistry.register('field_angle', FieldAngle);
+/** Register the field and any dependencies. */
+export function registerFieldAngle() {
+  // Unregister legacy field_angle that was in core.
+  // TODO(#2194): Delete this once core Blockly no longer defines field_angle.
+  // If field_angle is not defined in core, this generates a console warning.
+  Blockly.fieldRegistry.unregister('field_angle');
+
+  Blockly.fieldRegistry.register('field_angle', FieldAngle);
+}
 
 FieldAngle.prototype.DEFAULT_VALUE = 0;
 

plugins/field-angle/test/field_angle_test.mocha.js

@@ -5,7 +5,7 @@
  */
 
 const {testHelpers} = require('@blockly/dev-tools');
-const {FieldAngle} = require('../src/index');
+const {FieldAngle, registerFieldAngle} = require('../src/index');
 const {assert} = require('chai');
 
 const {
@@ -18,6 +18,10 @@ const {
 } = testHelpers;
 
 suite('FieldAngle', function () {
+  setup(function () {
+    registerFieldAngle();
+  });
+
   /**
    * Configuration for field tests with invalid values.
    * @type {Array<FieldCreationTestCase>}

plugins/field-angle/test/index.ts

@@ -10,7 +10,7 @@
 
 import * as Blockly from 'blockly';
 import {generateFieldTestBlocks, createPlayground} from '@blockly/dev-tools';
-import '../src/index';
+import {registerFieldAngle} from '../src/index';
 
 const toolbox = generateFieldTestBlocks('field_angle', [
   {
@@ -81,6 +81,7 @@ function createWorkspace(
 }
 
 document.addEventListener('DOMContentLoaded', function () {
+  registerFieldAngle();
   const defaultOptions: Blockly.BlocklyOptions = {
     toolbox,
   };

plugins/field-colour/README.md

@@ -1,6 +1,7 @@
 # @blockly/field-colour [![Built on Blockly](https://tinyurl.com/built-on-blockly)](https://github.com/google/blockly)
 
-A [Blockly](https://www.npmjs.com/package/blockly) colour field.
+A [Blockly](https://www.npmjs.com/package/blockly) field and blocks for
+choosing and combining colours.
 
 ## Installation
 
@@ -18,7 +19,9 @@ npm install @blockly/field-colour --save
 
 ## Usage
 
-This field accepts up to 4 parameters:
+### Field
+
+The colour field accepts up to 4 parameters:
 
 - "colour" to specify the default colour. Defaults to the first value in the
   "colourOptions" array. Should be a "#rrggbb" string.
@@ -30,11 +33,17 @@ This field accepts up to 4 parameters:
 - "columns" to specify the number of columns the colour dropdown should have.
   Defaults to 7.
 
-### JavaScript
+If you want to use only the field, you must register it with Blockly. You can
+do this by calling `registerFieldColour` before instantiating your blocks. If
+another field is registered under the same name, this field will overwrite it.
+
+#### JavaScript
 
 ```js
 import * as Blockly from 'blockly';
-import {FieldColour} from '@blockly/field-colour';
+import {registerFieldColour} from '@blockly/field-colour';
+
+registerFieldColour();
 Blockly.Blocks['test_field_colour'] = {
   init: function () {
     this.appendDummyInput()
@@ -44,11 +53,13 @@ Blockly.Blocks['test_field_colour'] = {
 };
 ```
 
-### JSON
+#### JSON
 
 ```js
 import * as Blockly from 'blockly';
-import '@blockly/field-colour';
+import {registerFieldColour} from '@blockly/field-colour';
+
+registerFieldColour();
 Blockly.defineBlocksWithJsonArray([
   {
     type: 'test_field_colour',
@@ -64,6 +75,55 @@ Blockly.defineBlocksWithJsonArray([
 ]);
 ```
 
+### Blocks
+
+This package also provides four blocks related to the colour field. Each block
+has generators in JavaScript, Python, PHP, Lua, and Dart.
+
+- "colour_blend" takes in two colours and a ratio and outputs a single colour.
+- "colour_picker" is a simple block with just the colour field and an output.
+- "colour_random" generates a random colour.
+- "colour_rgb" generates a colour based on red, green, and blue values.
+
+You can install all four blocks by calling `installAllBlocks`. This will
+install the blocks and all of their dependencies, including the colour field.
+When calling `installAllBlocks`—or any of the individual `installSomeBlock`
+functions—you can supply one or more `CodeGenerator` instances (e.g.
+`javascriptGenerator`), and the install function will also install the correct
+generator function for each block for the corresponding language(s).
+
+```js
+import {javascriptGenerator} from 'blockly/javascript';
+import {dartGenerator} from 'blockly/dart';
+import {phpGenerator} from 'blockly/php';
+import {pythonGenerator} from 'blockly/python';
+import {luaGenerator} from 'blockly/lua';
+import {installAllBlocks as installColourBlocks} from '@blockly/field-colour';
+
+// Installs all four blocks, the colour field, and all of the language generators.
+installColourBlocks({
+  javascript: javascriptGenerator,
+  dart: dartGenerator,
+  lua: luaGenerator,
+  python: pythonGenerator,
+  php: phpGenerator,
+});
+```
+
+If you only want to install a single block, you can call that block's
+`installBlock` function. The `generators` parameter is the same.
+
+```js
+import {javascriptGenerator} from 'blockly/javascript';
+import {colourBlend} from '@blockly/field-colour';
+
+// Installs the colour_blend block, the colour field,
+// and the generator for colour_blend in JavaScript.
+colourBlend.installBlock({
+  javascript: javascriptGenerator,
+});
+```
+
 ### API Reference
 
 - `setColours`: Sets the colour options, and optionally the titles for the