From b4ce6afd2a3c11de5dd062d55d1b50d3a8e5999a Mon Sep 17 00:00:00 2001
From: Beka Westberg <bwestberg@google.com>
Date: Wed, 16 Aug 2023 09:30:13 -0700
Subject: [PATCH] feat: add doFullSerialization support to blocks (#7363)

* feat: add doFullSerialization support to blocks

* chore: PR comments
---
 core/block.ts                      |  8 +++++++-
 core/events/events_block_change.ts |  2 +-
 core/field.ts                      |  3 +++
 core/serialization/blocks.ts       | 13 ++++++++++---
 4 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/core/block.ts b/core/block.ts
index ea85edaf8..a12ea85fe 100644
--- a/core/block.ts
+++ b/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
diff --git a/core/events/events_block_change.ts b/core/events/events_block_change.ts
index 242af9e73..a50cadc71 100644
--- a/core/events/events_block_change.ts
+++ b/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();
diff --git a/core/field.ts b/core/field.ts
index 08aa28486..d562782d1 100644
--- a/core/field.ts
+++ b/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
    */
diff --git a/core/serialization/blocks.ts b/core/serialization/blocks.ts
index f11a7d8cd..fa88e13ba 100644
--- a/core/serialization/blocks.ts
+++ b/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;
     }