feat: add doFullSerialization support to blocks (#7363)

* feat: add doFullSerialization support to blocks

* chore: PR comments

core/block.ts

@@ -120,8 +120,14 @@ export class Block implements IASTNodeLocation, IDeletable {
    * An optional serialization method for defining how to serialize the
    * block's extra state (eg mutation state) to something JSON compatible.
    * This must be coupled with defining `loadExtraState`.
+   *
+   * @param doFullSerialization Whether or not to serialize the full state of
+   *     the extra state (rather than possibly saving a reference to some
+   *     state). This is used during copy-paste. See the
+   *     {@link https://developers.devsite.google.com/blockly/guides/create-custom-blocks/extensions#full_serialization_and_backing_data | block serialization docs}
+   *     for more information.
    */
-  saveExtraState?: () => AnyDuringMigration;
+  saveExtraState?: (doFullSerialization?: boolean) => AnyDuringMigration;
 
   /**
    * An optional serialization method for defining how to deserialize the

core/events/events_block_change.ts

@@ -205,7 +205,7 @@ export class BlockChange extends BlockBase {
    */
   static getExtraBlockState_(block: BlockSvg): string {
     if (block.saveExtraState) {
-      const state = block.saveExtraState();
+      const state = block.saveExtraState(false);
       return state ? JSON.stringify(state) : '';
     } else if (block.mutationToDom) {
       const state = block.mutationToDom();

core/field.ts

@@ -423,6 +423,9 @@ export abstract class Field<T = any>
    * @param _doFullSerialization If true, this signals to the field that if it
    *     normally just saves a reference to some state (eg variable fields) it
    *     should instead serialize the full state of the thing being referenced.
+   *     See the
+   *     {@link https://developers.devsite.google.com/blockly/guides/create-custom-blocks/fields/customizing-fields/creating#full_serialization_and_backing_data | field serialization docs}
+   *     for more information.
    * @returns JSON serializable state.
    * @internal
    */

core/serialization/blocks.ts

@@ -113,7 +113,7 @@ export function save(
   saveAttributes(block, state as AnyDuringMigration);
   // AnyDuringMigration because:  Argument of type '{ type: string; id: string;
   // }' is not assignable to parameter of type 'State'.
-  saveExtraState(block, state as AnyDuringMigration);
+  saveExtraState(block, state as AnyDuringMigration, doFullSerialization);
   // AnyDuringMigration because:  Argument of type '{ type: string; id: string;
   // }' is not assignable to parameter of type 'State'.
   saveIcons(block, state as AnyDuringMigration, doFullSerialization);
@@ -183,15 +183,22 @@ function saveCoords(block: Block, state: State) {
   state['x'] = Math.round(workspace.RTL ? workspace.getWidth() - xy.x : xy.x);
   state['y'] = Math.round(xy.y);
 }
+
 /**
  * Adds any extra state the block may provide to the given state object.
  *
  * @param block The block to serialize the extra state of.
  * @param state The state object to append to.
+ * @param doFullSerialization Whether or not to serialize the full state of the
+ *     extra state (rather than possibly saving a reference to some state).
  */
-function saveExtraState(block: Block, state: State) {
+function saveExtraState(
+  block: Block,
+  state: State,
+  doFullSerialization: boolean,
+) {
   if (block.saveExtraState) {
-    const extraState = block.saveExtraState();
+    const extraState = block.saveExtraState(doFullSerialization);
     if (extraState !== null) {
       state['extraState'] = extraState;
     }