blockly 12.3.1 → 12.4.0

package/core/serialization/exceptions.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.serialization.exceptions
+
+import type {Block} from '../block.js';
+import type {State} from './blocks.js';
+
+export class DeserializationError extends Error {}
+
+/**
+ * Represents an error where the serialized state is expected to provide a
+ * block type, but it is not provided.
+ *
+ */
+export class MissingBlockType extends DeserializationError {
+  /**
+   * @param state The state object which is missing the block type.
+   * @internal
+   */
+  constructor(public state: State) {
+    super(`Expected to find a 'type' property, defining the block type`);
+  }
+}
+
+/**
+ * Represents an error where deserialization encountered a block that did
+ * not have a connection that was defined in the serialized state.
+ */
+export class MissingConnection extends DeserializationError {
+  /**
+   * @param connection The name of the connection that is missing. E.g.
+   *     'IF0', or 'next'.
+   * @param block The block missing the connection.
+   * @param state The state object containing the bad connection.
+   * @internal
+   */
+  constructor(
+    connection: string,
+    public block: Block,
+    public state: State,
+  ) {
+    super(`The block ${block.toDevString()} is missing a(n) ${connection}
+connection`);
+  }
+}
+
+/**
+ * Represents an error where deserialization tried to connect two connections
+ * that were not compatible.
+ */
+export class BadConnectionCheck extends DeserializationError {
+  /**
+   * @param reason The reason the connections were not compatible.
+   * @param childConnection The name of the incompatible child connection. E.g.
+   *     'output' or 'previous'.
+   * @param childBlock The child block that could not connect to its parent.
+   * @param childState The state object representing the child block.
+   * @internal
+   */
+  constructor(
+    reason: string,
+    childConnection: string,
+    public childBlock: Block,
+    public childState: State,
+  ) {
+    super(`The block ${childBlock.toDevString()} could not connect its
+${childConnection} to its parent, because: ${reason}`);
+  }
+}
+
+/**
+ * Represents an error where deserialization encountered a real block as it
+ * was deserializing children of a shadow.
+ * This is an error because it is an invariant of Blockly that shadow blocks
+ * do not have real children.
+ */
+export class RealChildOfShadow extends DeserializationError {
+  /**
+   * @param state The state object representing the real block.
+   * @internal
+   */
+  constructor(public state: State) {
+    super(`Encountered a real block which is defined as a child of a shadow
+block. It is an invariant of Blockly that shadow blocks only have shadow
+children`);
+  }
+}
+
+export class UnregisteredIcon extends DeserializationError {
+  /**
+   * @param iconType The type of the unregistered icon we are attempting to
+   *     deserialize.
+   * @param block The block we are attempting to add the unregistered icon to.
+   * @param state The state object representing the block.
+   */
+  constructor(
+    iconType: string,
+    public block: Block,
+    public state: State,
+  ) {
+    super(
+      `Cannot add an icon of type '${iconType}' to the block ` +
+        `${block.toDevString()}, because there is no icon registered with ` +
+        `type '${iconType}'. Make sure that all of your icons have been ` +
+        `registered.`,
+    );
+  }
+}

package/core/serialization/priorities.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.serialization.priorities
+
+/**
+ * The priority for deserializing variables.
+ */
+export const VARIABLES = 100;
+
+/**
+ * The priority for deserializing variable data.
+ */
+export const PROCEDURES = 75;
+
+/**
+ * The priority for deserializing blocks.
+ */
+export const BLOCKS = 50;
+
+/** The priority for deserializing workspace comments. */
+export const WORKSPACE_COMMENTS = 25;

package/core/serialization/procedures.ts

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {IParameterModel} from '../interfaces/i_parameter_model.js';
+import {IProcedureModel} from '../interfaces/i_procedure_model.js';
+import type {ISerializer} from '../interfaces/i_serializer.js';
+import type {Workspace} from '../workspace.js';
+import * as priorities from './priorities.js';
+
+/** Represents the state of a procedure model. */
+export interface State {
+  id: string;
+  name: string;
+  returnTypes: string[] | null;
+  parameters?: ParameterState[];
+  [key: string]: unknown;
+}
+
+/** Represents the state of a parameter model. */
+export interface ParameterState {
+  id: string;
+  name: string;
+  types?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * A newable signature for an IProcedureModel.
+ *
+ * Refer to
+ * https://www.typescriptlang.org/docs/handbook/interfaces.html#difference-between-the-static-and-instance-sides-of-classes
+ * for what is going on with this.
+ */
+interface ProcedureModelConstructor<ProcedureModel extends IProcedureModel> {
+  new (workspace: Workspace, name: string, id: string): ProcedureModel;
+
+  /**
+   * Deserializes the JSON state and returns a procedure model.
+   *
+   * @param state The state to deserialize.
+   * @param workspace The workspace to load the procedure model into.
+   * @returns The constructed procedure model.
+   */
+  loadState(state: object, workspace: Workspace): ProcedureModel;
+}
+
+/**
+ * A newable signature for an IParameterModel.
+ *
+ * Refer to
+ * https://www.typescriptlang.org/docs/handbook/interfaces.html#difference-between-the-static-and-instance-sides-of-classes
+ * for what is going on with this.
+ */
+interface ParameterModelConstructor<ParameterModel extends IParameterModel> {
+  new (workspace: Workspace, name: string, id: string): ParameterModel;
+
+  /**
+   * Deserializes the JSON state and returns a parameter model.
+   *
+   * @param state The state to deserialize.
+   * @param workspace The workspace to load the parameter model into.
+   * @returns The constructed parameter model.
+   */
+  loadState(state: object, workspace: Workspace): ParameterModel;
+}
+
+/**
+ * Serializes the given IProcedureModel to JSON.
+ */
+export function saveProcedure(proc: IProcedureModel): State {
+  const state: State = proc.saveState();
+  if (!proc.getParameters().length) return state;
+  state.parameters = proc.getParameters().map((param) => param.saveState());
+  return state;
+}
+
+/**
+ * Deserializes the given procedure model State from JSON.
+ */
+export function loadProcedure<
+  ProcedureModel extends IProcedureModel,
+  ParameterModel extends IParameterModel,
+>(
+  procedureModelClass: ProcedureModelConstructor<ProcedureModel>,
+  parameterModelClass: ParameterModelConstructor<ParameterModel>,
+  state: State,
+  workspace: Workspace,
+): ProcedureModel {
+  const proc = procedureModelClass.loadState(state, workspace);
+  if (!state.parameters) return proc;
+  for (const [index, param] of state.parameters.entries()) {
+    proc.insertParameter(
+      parameterModelClass.loadState(param, workspace),
+      index,
+    );
+  }
+  return proc;
+}
+
+/** Serializer for saving and loading procedure state. */
+export class ProcedureSerializer<
+  ProcedureModel extends IProcedureModel,
+  ParameterModel extends IParameterModel,
+> implements ISerializer
+{
+  public priority = priorities.PROCEDURES;
+
+  /**
+   * Constructs the procedure serializer.
+   *
+   * Example usage:
+   *   new ProcedureSerializer(MyProcedureModelClass, MyParameterModelClass)
+   *
+   * @param procedureModelClass The class (implementing IProcedureModel) that
+   *     you want this serializer to deserialize.
+   * @param parameterModelClass The class (implementing IParameterModel) that
+   *     you want this serializer to deserialize.
+   */
+  constructor(
+    private readonly procedureModelClass: ProcedureModelConstructor<ProcedureModel>,
+    private readonly parameterModelClass: ParameterModelConstructor<ParameterModel>,
+  ) {}
+
+  /** Serializes the procedure models of the given workspace. */
+  save(workspace: Workspace): State[] | null {
+    const save = workspace
+      .getProcedureMap()
+      .getProcedures()
+      .map((proc) => saveProcedure(proc));
+    return save.length ? save : null;
+  }
+
+  /**
+   * Deserializes the procedures models defined by the given state into the
+   * workspace.
+   */
+  load(state: State[], workspace: Workspace) {
+    const map = workspace.getProcedureMap();
+    for (const procState of state) {
+      map.add(
+        loadProcedure(
+          this.procedureModelClass,
+          this.parameterModelClass,
+          procState,
+          workspace,
+        ),
+      );
+    }
+  }
+
+  /** Disposes of any procedure models that exist on the workspace. */
+  clear(workspace: Workspace) {
+    workspace.getProcedureMap().clear();
+  }
+}

package/core/serialization/registry.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.serialization.registry
+
+import type {ISerializer} from '../interfaces/i_serializer.js';
+import * as registry from '../registry.js';
+
+/**
+ * Registers the given serializer so that it can be used for serialization and
+ * deserialization.
+ *
+ * @param name The name of the serializer to register.
+ * @param serializer The serializer to register.
+ */
+export function register(name: string, serializer: ISerializer) {
+  registry.register(registry.Type.SERIALIZER, name, serializer);
+}
+
+/**
+ * Unregisters the serializer associated with the given name.
+ *
+ * @param name The name of the serializer to unregister.
+ */
+export function unregister(name: string) {
+  registry.unregister(registry.Type.SERIALIZER, name);
+}

package/core/serialization/variables.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.serialization.variables
+
+import type {ISerializer} from '../interfaces/i_serializer.js';
+import type {IVariableState} from '../interfaces/i_variable_model.js';
+import * as registry from '../registry.js';
+import type {Workspace} from '../workspace.js';
+import * as priorities from './priorities.js';
+import * as serializationRegistry from './registry.js';
+
+/**
+ * Serializer for saving and loading variable state.
+ */
+export class VariableSerializer implements ISerializer {
+  priority: number;
+
+  constructor() {
+    /** The priority for deserializing variables. */
+    this.priority = priorities.VARIABLES;
+  }
+
+  /**
+   * Serializes the variables of the given workspace.
+   *
+   * @param workspace The workspace to save the variables of.
+   * @returns The state of the workspace's variables, or null if there are no
+   *     variables.
+   */
+  save(workspace: Workspace): IVariableState[] | null {
+    const variableStates = workspace
+      .getVariableMap()
+      .getAllVariables()
+      .map((v) => v.save());
+    return variableStates.length ? variableStates : null;
+  }
+
+  /**
+   * Deserializes the variable defined by the given state into the given
+   * workspace.
+   *
+   * @param state The state of the variables to deserialize.
+   * @param workspace The workspace to deserialize into.
+   */
+  load(state: IVariableState[], workspace: Workspace) {
+    const VariableModel = registry.getObject(
+      registry.Type.VARIABLE_MODEL,
+      registry.DEFAULT,
+    );
+    state.forEach((s) => {
+      VariableModel?.load(s, workspace);
+    });
+  }
+
+  /**
+   * Disposes of any variables that exist on the workspace.
+   *
+   * @param workspace The workspace to clear the variables of.
+   */
+  clear(workspace: Workspace) {
+    workspace.getVariableMap().clear();
+  }
+}
+
+serializationRegistry.register('variables', new VariableSerializer());

package/core/serialization/workspace_comments.ts

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {WorkspaceComment} from '../comments/workspace_comment.js';
+import * as eventUtils from '../events/utils.js';
+import {ISerializer} from '../interfaces/i_serializer.js';
+import {Coordinate} from '../utils/coordinate.js';
+import {Size} from '../utils/size.js';
+import {Workspace} from '../workspace.js';
+import * as priorities from './priorities.js';
+import * as serializationRegistry from './registry.js';
+
+export interface State {
+  id?: string;
+  text?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  collapsed?: boolean;
+  editable?: boolean;
+  movable?: boolean;
+  deletable?: boolean;
+}
+
+/** Serializes the state of the given comment to JSON. */
+export function save(
+  comment: WorkspaceComment,
+  {
+    addCoordinates = false,
+    saveIds = true,
+  }: {
+    addCoordinates?: boolean;
+    saveIds?: boolean;
+  } = {},
+): State {
+  const workspace = comment.workspace;
+  const state: State = Object.create(null);
+
+  state.height = comment.getSize().height;
+  state.width = comment.getSize().width;
+
+  if (saveIds) state.id = comment.id;
+  if (addCoordinates) {
+    const loc = comment.getRelativeToSurfaceXY();
+    state.x = workspace.RTL ? workspace.getWidth() - loc.x : loc.x;
+    state.y = loc.y;
+  }
+
+  if (comment.getText()) state.text = comment.getText();
+  if (comment.isCollapsed()) state.collapsed = true;
+  if (!comment.isOwnEditable()) state.editable = false;
+  if (!comment.isOwnMovable()) state.movable = false;
+  if (!comment.isOwnDeletable()) state.deletable = false;
+
+  return state;
+}
+
+/** Appends the comment defined by the given state to the given workspace. */
+export function append(
+  state: State,
+  workspace: Workspace,
+  {recordUndo = false}: {recordUndo?: boolean} = {},
+): WorkspaceComment {
+  const prevRecordUndo = eventUtils.getRecordUndo();
+  eventUtils.setRecordUndo(recordUndo);
+
+  const comment = workspace.newComment(state.id);
+
+  if (state.text !== undefined) comment.setText(state.text);
+  if (state.x !== undefined || state.y !== undefined) {
+    const defaultLoc = comment.getRelativeToSurfaceXY();
+    let x = state.x ?? defaultLoc.x;
+    x = workspace.RTL ? workspace.getWidth() - x : x;
+    const y = state.y ?? defaultLoc.y;
+    comment.moveTo(new Coordinate(x, y));
+  }
+  if (state.width !== undefined || state.height) {
+    const defaultSize = comment.getSize();
+    comment.setSize(
+      new Size(
+        state.width ?? defaultSize.width,
+        state.height ?? defaultSize.height,
+      ),
+    );
+  }
+  if (state.collapsed !== undefined) comment.setCollapsed(state.collapsed);
+  if (state.editable !== undefined) comment.setEditable(state.editable);
+  if (state.movable !== undefined) comment.setMovable(state.movable);
+  if (state.deletable !== undefined) comment.setDeletable(state.deletable);
+
+  eventUtils.setRecordUndo(prevRecordUndo);
+
+  return comment;
+}
+
+// Alias to disambiguate saving within the serializer.
+const saveComment = save;
+
+/** Serializer for saving and loading workspace comment state. */
+export class WorkspaceCommentSerializer implements ISerializer {
+  priority = priorities.WORKSPACE_COMMENTS;
+
+  /**
+   * Returns the state of all workspace comments in the given workspace.
+   */
+  save(workspace: Workspace): State[] | null {
+    const commentStates = [];
+    for (const comment of workspace.getTopComments()) {
+      const state = saveComment(comment, {
+        addCoordinates: true,
+        saveIds: true,
+      });
+      if (state) commentStates.push(state);
+    }
+    return commentStates.length ? commentStates : null;
+  }
+
+  /**
+   * Deserializes the comments defined by the given state into the given
+   * workspace.
+   */
+  load(state: State[], workspace: Workspace) {
+    for (const commentState of state) {
+      append(commentState, workspace, {recordUndo: eventUtils.getRecordUndo()});
+    }
+  }
+
+  /** Disposes of any comments that exist on the given workspace. */
+  clear(workspace: Workspace) {
+    for (const comment of workspace.getTopComments()) {
+      comment.dispose();
+    }
+  }
+}
+
+serializationRegistry.register(
+  'workspaceComments',
+  new WorkspaceCommentSerializer(),
+);

package/core/serialization/workspaces.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.serialization.workspaces
+
+import {EventType} from '../events/type.js';
+import * as eventUtils from '../events/utils.js';
+import type {ISerializer} from '../interfaces/i_serializer.js';
+import * as registry from '../registry.js';
+import * as dom from '../utils/dom.js';
+import type {Workspace} from '../workspace.js';
+import {WorkspaceSvg} from '../workspace_svg.js';
+
+/**
+ * Returns the state of the workspace as a plain JavaScript object.
+ *
+ * @param workspace The workspace to serialize.
+ * @returns The serialized state of the workspace.
+ */
+export function save(workspace: Workspace): {
+  [key: string]: AnyDuringMigration;
+} {
+  const state = Object.create(null);
+  const serializerMap = registry.getAllItems(registry.Type.SERIALIZER, true);
+  for (const key in serializerMap) {
+    const save = (serializerMap[key] as ISerializer)?.save(workspace);
+    if (save) {
+      state[key] = save;
+    }
+  }
+  return state;
+}
+
+/**
+ * Loads the variable represented by the given state into the given workspace.
+ *
+ * @param state The state of the workspace to deserialize into the workspace.
+ * @param workspace The workspace to add the new state to.
+ * @param param1 recordUndo: If true, events triggered by this function will be
+ *     undo-able by the user. False by default.
+ */
+export function load(
+  state: {[key: string]: AnyDuringMigration},
+  workspace: Workspace,
+  {recordUndo = false}: {recordUndo?: boolean} = {},
+) {
+  const serializerMap = registry.getAllItems(registry.Type.SERIALIZER, true);
+  if (!serializerMap) {
+    return;
+  }
+
+  const deserializers = Object.entries(serializerMap).sort(
+    (a, b) => (b[1] as ISerializer)!.priority - (a[1] as ISerializer)!.priority,
+  );
+
+  const prevRecordUndo = eventUtils.getRecordUndo();
+  eventUtils.setRecordUndo(recordUndo);
+  const existingGroup = eventUtils.getGroup();
+  if (!existingGroup) {
+    eventUtils.setGroup(true);
+  }
+
+  dom.startTextWidthCache();
+  if (workspace instanceof WorkspaceSvg) {
+    workspace.setResizesEnabled(false);
+  }
+
+  // We want to trigger clearing in reverse priority order so plugins don't end
+  // up missing dependencies.
+  for (const [, deserializer] of deserializers.reverse()) {
+    (deserializer as ISerializer)?.clear(workspace);
+  }
+
+  // reverse() is destructive, so we have to re-reverse to correct the order.
+  for (const [name, deserializer] of deserializers.reverse()) {
+    const pluginState = state[name];
+    if (pluginState) {
+      (deserializer as ISerializer)?.load(state[name], workspace);
+    }
+  }
+
+  if (workspace instanceof WorkspaceSvg) {
+    workspace.setResizesEnabled(true);
+  }
+  dom.stopTextWidthCache();
+
+  eventUtils.fire(new (eventUtils.get(EventType.FINISHED_LOADING))(workspace));
+
+  eventUtils.setGroup(existingGroup);
+  eventUtils.setRecordUndo(prevRecordUndo);
+}

package/core/serialization.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Serialization methods.
+ */
+// Former goog.module ID: Blockly.serialization
+
+import {ISerializer} from './interfaces/i_serializer.js';
+import * as blocks from './serialization/blocks.js';
+import * as exceptions from './serialization/exceptions.js';
+import * as priorities from './serialization/priorities.js';
+import * as procedures from './serialization/procedures.js';
+import * as registry from './serialization/registry.js';
+import * as variables from './serialization/variables.js';
+import * as workspaceComments from './serialization/workspace_comments.js';
+import * as workspaces from './serialization/workspaces.js';
+
+export {
+  blocks,
+  exceptions,
+  ISerializer,
+  priorities,
+  procedures,
+  registry,
+  variables,
+  workspaceComments,
+  workspaces,
+};