blockly 12.3.0 → 12.4.0

package/core/utils/toolbox.ts

@@ -0,0 +1,417 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.toolbox
+
+import type {ConnectionState} from '../serialization/blocks.js';
+import type {CssConfig as CategoryCssConfig} from '../toolbox/category.js';
+import type {CssConfig as SeparatorCssConfig} from '../toolbox/separator.js';
+import * as utilsXml from './xml.js';
+
+/**
+ * The information needed to create a block in the toolbox.
+ * Note that disabled has a different type for backwards compatibility.
+ */
+export interface BlockInfo {
+  kind: string;
+  blockxml?: string | Node;
+  type?: string;
+  gap?: string | number;
+  disabled?: string | boolean;
+  disabledReasons?: string[];
+  enabled?: boolean;
+  id?: string;
+  collapsed?: boolean;
+  inline?: boolean;
+  data?: string;
+  extraState?: AnyDuringMigration;
+  icons?: {[key: string]: AnyDuringMigration};
+  fields?: {[key: string]: AnyDuringMigration};
+  inputs?: {[key: string]: ConnectionState};
+  next?: ConnectionState;
+}
+
+/**
+ * The information needed to create a separator in the toolbox.
+ */
+export interface SeparatorInfo {
+  kind: string;
+  id: string | undefined;
+  gap: number | undefined;
+  cssconfig: SeparatorCssConfig | undefined;
+}
+
+/**
+ * The information needed to create a button in the toolbox.
+ */
+export interface ButtonInfo {
+  kind: string;
+  text: string;
+  callbackkey: string;
+}
+
+/**
+ * The information needed to create a label in the toolbox.
+ */
+export interface LabelInfo {
+  kind: string;
+  text: string;
+  id: string | undefined;
+}
+
+/**
+ * The information needed to create either a button or a label in the flyout.
+ */
+export type ButtonOrLabelInfo = ButtonInfo | LabelInfo;
+
+/**
+ * The information needed to create a category in the toolbox.
+ */
+export interface StaticCategoryInfo {
+  kind: string;
+  name: string;
+  contents: ToolboxItemInfo[];
+  id: string | undefined;
+  categorystyle: string | undefined;
+  colour: string | undefined;
+  cssconfig: CategoryCssConfig | undefined;
+  hidden: string | undefined;
+  expanded?: string | boolean;
+}
+
+/**
+ * The information needed to create a custom category.
+ */
+export interface DynamicCategoryInfo {
+  kind: string;
+  custom: string;
+  id: string | undefined;
+  categorystyle: string | undefined;
+  colour: string | undefined;
+  cssconfig: CategoryCssConfig | undefined;
+  hidden: string | undefined;
+  expanded?: string | boolean;
+}
+
+/**
+ * The information needed to create either a dynamic or static category.
+ */
+export type CategoryInfo = StaticCategoryInfo | DynamicCategoryInfo;
+
+/**
+ * Any information that can be used to create an item in the toolbox.
+ */
+export type ToolboxItemInfo = FlyoutItemInfo | StaticCategoryInfo;
+
+/**
+ * All the different types that can be displayed in a flyout.
+ */
+export type FlyoutItemInfo =
+  | BlockInfo
+  | SeparatorInfo
+  | ButtonInfo
+  | LabelInfo
+  | DynamicCategoryInfo;
+
+/**
+ * The JSON definition of a toolbox.
+ */
+export interface ToolboxInfo {
+  kind?: string;
+  contents: ToolboxItemInfo[];
+}
+
+/**
+ * An array holding flyout items.
+ */
+export type FlyoutItemInfoArray = FlyoutItemInfo[];
+
+/**
+ * All of the different types that can create a toolbox.
+ */
+export type ToolboxDefinition = Node | ToolboxInfo | string;
+
+/**
+ * All of the different types that can be used to show items in a flyout.
+ */
+export type FlyoutDefinition =
+  | FlyoutItemInfoArray
+  | NodeList
+  | ToolboxInfo
+  | Node[];
+
+/**
+ * The name used to identify a toolbox that has category like items.
+ * This only needs to be used if a toolbox wants to be treated like a category
+ * toolbox but does not actually contain any toolbox items with the kind
+ * 'category'.
+ */
+const CATEGORY_TOOLBOX_KIND = 'categoryToolbox';
+
+/**
+ * The name used to identify a toolbox that has no categories and is displayed
+ * as a simple flyout displaying blocks, buttons, or labels.
+ */
+const FLYOUT_TOOLBOX_KIND = 'flyoutToolbox';
+
+/**
+ * Position of the toolbox and/or flyout relative to the workspace.
+ */
+export enum Position {
+  TOP,
+  BOTTOM,
+  LEFT,
+  RIGHT,
+}
+
+/**
+ * Converts the toolbox definition into toolbox JSON.
+ *
+ * @param toolboxDef The definition of the toolbox in one of its many forms.
+ * @returns Object holding information for creating a toolbox.
+ * @internal
+ */
+export function convertToolboxDefToJson(
+  toolboxDef: ToolboxDefinition | null,
+): ToolboxInfo | null {
+  if (!toolboxDef) {
+    return null;
+  }
+
+  if (toolboxDef instanceof Element || typeof toolboxDef === 'string') {
+    toolboxDef = parseToolboxTree(toolboxDef);
+    // AnyDuringMigration because:  Argument of type 'Node | null' is not
+    // assignable to parameter of type 'Node'.
+    toolboxDef = convertToToolboxJson(toolboxDef as AnyDuringMigration);
+  }
+
+  const toolboxJson = toolboxDef as ToolboxInfo;
+  validateToolbox(toolboxJson);
+  return toolboxJson;
+}
+
+/**
+ * Validates the toolbox JSON fields have been set correctly.
+ *
+ * @param toolboxJson Object holding information for creating a toolbox.
+ * @throws {Error} if the toolbox is not the correct format.
+ */
+function validateToolbox(toolboxJson: ToolboxInfo) {
+  const toolboxKind = toolboxJson['kind'];
+  const toolboxContents = toolboxJson['contents'];
+
+  if (toolboxKind) {
+    if (
+      toolboxKind !== FLYOUT_TOOLBOX_KIND &&
+      toolboxKind !== CATEGORY_TOOLBOX_KIND
+    ) {
+      throw Error(
+        'Invalid toolbox kind ' +
+          toolboxKind +
+          '.' +
+          ' Please supply either ' +
+          FLYOUT_TOOLBOX_KIND +
+          ' or ' +
+          CATEGORY_TOOLBOX_KIND,
+      );
+    }
+  }
+  if (!toolboxContents) {
+    throw Error('Toolbox must have a contents attribute.');
+  }
+}
+
+/**
+ * Converts the flyout definition into a list of flyout items.
+ *
+ * @param flyoutDef The definition of the flyout in one of its many forms.
+ * @returns A list of flyout items.
+ * @internal
+ */
+export function convertFlyoutDefToJsonArray(
+  flyoutDef: FlyoutDefinition | null,
+): FlyoutItemInfoArray {
+  if (!flyoutDef) {
+    return [];
+  }
+
+  if ((flyoutDef as AnyDuringMigration)['contents']) {
+    return (flyoutDef as AnyDuringMigration)['contents'];
+  }
+  // If it is already in the correct format return the flyoutDef.
+  // AnyDuringMigration because:  Property 'nodeType' does not exist on type
+  // 'Node | FlyoutItemInfo'.
+  if (
+    Array.isArray(flyoutDef) &&
+    flyoutDef.length > 0 &&
+    !(flyoutDef[0] as AnyDuringMigration).nodeType
+  ) {
+    // AnyDuringMigration because:  Type 'FlyoutItemInfoArray | Node[]' is not
+    // assignable to type 'FlyoutItemInfoArray'.
+    return flyoutDef as AnyDuringMigration;
+  }
+
+  // AnyDuringMigration because:  Type 'ToolboxItemInfo[] | FlyoutItemInfoArray'
+  // is not assignable to type 'FlyoutItemInfoArray'.
+  return xmlToJsonArray(flyoutDef as Node[] | NodeList) as AnyDuringMigration;
+}
+
+/**
+ * Whether or not the toolbox definition has categories.
+ *
+ * @param toolboxJson Object holding information for creating a toolbox.
+ * @returns True if the toolbox has categories.
+ * @internal
+ */
+export function hasCategories(toolboxJson: ToolboxInfo | null): boolean {
+  return TEST_ONLY.hasCategoriesInternal(toolboxJson);
+}
+
+/**
+ * Private version of hasCategories for stubbing in tests.
+ */
+function hasCategoriesInternal(toolboxJson: ToolboxInfo | null): boolean {
+  if (!toolboxJson) {
+    return false;
+  }
+
+  const toolboxKind = toolboxJson['kind'];
+  if (toolboxKind) {
+    return toolboxKind === CATEGORY_TOOLBOX_KIND;
+  }
+
+  const categories = toolboxJson['contents'].filter(
+    (item) => item['kind'].toUpperCase() === 'CATEGORY',
+  );
+  return !!categories.length;
+}
+
+/**
+ * Whether or not the category is collapsible.
+ *
+ * @param categoryInfo Object holing information for creating a category.
+ * @returns True if the category has subcategories.
+ * @internal
+ */
+export function isCategoryCollapsible(categoryInfo: CategoryInfo): boolean {
+  if (!categoryInfo || !(categoryInfo as AnyDuringMigration)['contents']) {
+    return false;
+  }
+
+  const categories = (categoryInfo as AnyDuringMigration)['contents'].filter(
+    function (item: AnyDuringMigration) {
+      return item['kind'].toUpperCase() === 'CATEGORY';
+    },
+  );
+  return !!categories.length;
+}
+
+/**
+ * Parses the provided toolbox definition into a consistent format.
+ *
+ * @param toolboxDef The definition of the toolbox in one of its many forms.
+ * @returns Object holding information for creating a toolbox.
+ */
+function convertToToolboxJson(toolboxDef: Node): ToolboxInfo {
+  const contents = xmlToJsonArray(toolboxDef as Node | Node[]);
+  const toolboxJson = {'contents': contents};
+  if (toolboxDef instanceof Node) {
+    addAttributes(toolboxDef, toolboxJson);
+  }
+  return toolboxJson;
+}
+
+/**
+ * Converts the xml for a toolbox to JSON.
+ *
+ * @param toolboxDef The definition of the toolbox in one of its many forms.
+ * @returns A list of objects in the toolbox.
+ */
+function xmlToJsonArray(
+  toolboxDef: Node | Node[] | NodeList,
+): FlyoutItemInfoArray | ToolboxItemInfo[] {
+  const arr = [];
+  // If it is a node it will have children.
+  // AnyDuringMigration because:  Property 'childNodes' does not exist on type
+  // 'Node | NodeList | Node[]'.
+  let childNodes = (toolboxDef as AnyDuringMigration).childNodes;
+  if (!childNodes) {
+    // Otherwise the toolboxDef is an array or collection.
+    childNodes = toolboxDef;
+  }
+  for (let i = 0, child; (child = childNodes[i]); i++) {
+    if (!child.tagName) {
+      continue;
+    }
+    const obj = {};
+    const tagName = child.tagName.toUpperCase();
+    (obj as AnyDuringMigration)['kind'] = tagName;
+
+    // Store the XML for a block.
+    if (tagName === 'BLOCK') {
+      (obj as AnyDuringMigration)['blockxml'] = child;
+    } else if (child.childNodes && child.childNodes.length > 0) {
+      // Get the contents of a category
+      (obj as AnyDuringMigration)['contents'] = xmlToJsonArray(child);
+    }
+
+    // Add XML attributes to object
+    addAttributes(child, obj);
+    arr.push(obj);
+  }
+  // AnyDuringMigration because:  Type '{}[]' is not assignable to type
+  // 'ToolboxItemInfo[] | FlyoutItemInfoArray'.
+  return arr as AnyDuringMigration;
+}
+
+/**
+ * Adds the attributes on the node to the given object.
+ *
+ * @param node The node to copy the attributes from.
+ * @param obj The object to copy the attributes to.
+ */
+function addAttributes(node: Node, obj: AnyDuringMigration) {
+  // AnyDuringMigration because:  Property 'attributes' does not exist on type
+  // 'Node'.
+  for (let j = 0; j < (node as AnyDuringMigration).attributes.length; j++) {
+    // AnyDuringMigration because:  Property 'attributes' does not exist on type
+    // 'Node'.
+    const attr = (node as AnyDuringMigration).attributes[j];
+    if (attr.nodeName.includes('css-')) {
+      obj['cssconfig'] = obj['cssconfig'] || {};
+      obj['cssconfig'][attr.nodeName.replace('css-', '')] = attr.value;
+    } else {
+      obj[attr.nodeName] = attr.value;
+    }
+  }
+}
+
+/**
+ * Parse the provided toolbox tree into a consistent DOM format.
+ *
+ * @param toolboxDef DOM tree of blocks, or text representation of same.
+ * @returns DOM tree of blocks, or null.
+ */
+export function parseToolboxTree(
+  toolboxDef: Element | null | string,
+): Element | null {
+  let parsedToolboxDef: Element | null = null;
+  if (toolboxDef) {
+    if (typeof toolboxDef === 'string') {
+      parsedToolboxDef = utilsXml.textToDom(toolboxDef);
+      if (parsedToolboxDef.nodeName.toLowerCase() !== 'xml') {
+        throw TypeError('Toolbox should be an <xml> document.');
+      }
+    } else if (toolboxDef instanceof Element) {
+      parsedToolboxDef = toolboxDef;
+    }
+  }
+  return parsedToolboxDef;
+}
+
+export const TEST_ONLY = {
+  hasCategoriesInternal,
+};

package/core/utils/useragent.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.userAgent
+
+/** The raw useragent string. */
+let rawUserAgent: string;
+
+let isJavaFx: boolean;
+
+let isWebKit: boolean;
+
+let isGecko: boolean;
+
+let isAndroid: boolean;
+
+let isIPad: boolean;
+
+let isIPhone: boolean;
+
+let isMac: boolean;
+
+let isTablet: boolean;
+
+let isMobile: boolean;
+
+(function (raw) {
+  rawUserAgent = raw;
+  const rawUpper = rawUserAgent.toUpperCase();
+  /**
+   * Case-insensitive test of whether name is in the useragent string.
+   *
+   * @param name Name to test.
+   * @returns True if name is present.
+   */
+  function has(name: string): boolean {
+    return rawUpper.includes(name.toUpperCase());
+  }
+
+  // Browsers.  Logic from:
+  // https://github.com/google/closure-library/blob/master/closure/goog/labs/useragent/browser.js
+  // Useragent for JavaFX:
+  // Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.44
+  //     (KHTML, like Gecko) JavaFX/8.0 Safari/537.44
+  isJavaFx = has('JavaFX');
+
+  // Engines.  Logic from:
+  // https://github.com/google/closure-library/blob/master/closure/goog/labs/useragent/engine.js
+  isWebKit = has('WebKit');
+  isGecko = has('Gecko') && !isWebKit;
+
+  // Platforms.  Logic from:
+  // https://github.com/google/closure-library/blob/master/closure/goog/labs/useragent/platform.js
+  // and
+  // https://github.com/google/closure-library/blob/master/closure/goog/labs/useragent/extra.js
+  isAndroid = has('Android');
+  const maxTouchPoints =
+    globalThis['navigator'] && globalThis['navigator']['maxTouchPoints'];
+  isIPad = has('iPad') || (has('Macintosh') && maxTouchPoints > 0);
+  isIPhone = has('iPhone') && !isIPad;
+  isMac = has('Macintosh');
+
+  // Devices.  Logic from:
+  // https://github.com/google/closure-library/blob/master/closure/goog/labs/useragent/device.js
+  isTablet = isIPad || (isAndroid && !has('Mobile')) || has('Silk');
+  isMobile = !isTablet && (isIPhone || isAndroid);
+})((globalThis['navigator'] && globalThis['navigator']['userAgent']) || '');
+
+export const raw: string = rawUserAgent;
+
+export const JavaFx: boolean = isJavaFx;
+
+export const GECKO: boolean = isGecko;
+
+export const ANDROID: boolean = isAndroid;
+
+export const IPAD: boolean = isIPad;
+
+export const IPHONE: boolean = isIPhone;
+
+export const MAC: boolean = isMac;
+
+export const MOBILE: boolean = isMobile;

package/core/utils/xml.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.xml
+
+let domParser: DOMParser = {
+  parseFromString: function () {
+    throw new Error(
+      'DOMParser was not found in the global scope and was not properly ' +
+        'injected using injectDependencies',
+    );
+  },
+};
+
+let xmlSerializer: XMLSerializer = {
+  serializeToString: function () {
+    throw new Error(
+      'XMLSerializer was not foundin the global scope and was not properly ' +
+        'injected using injectDependencies',
+    );
+  },
+};
+
+/**
+ * Injected dependencies.  By default these are just (and have the
+ * same types as) the corresponding DOM Window properties, but the
+ * Node.js wrapper for Blockly (see scripts/package/node/core.js)
+ * calls injectDependencies to supply implementations from the jsdom
+ * package instead.
+ */
+let {document, DOMParser, XMLSerializer} = globalThis;
+if (DOMParser) domParser = new DOMParser();
+if (XMLSerializer) xmlSerializer = new XMLSerializer();
+
+/**
+ * Inject implementations of document, DOMParser and/or XMLSerializer
+ * to use instead of the default ones.
+ *
+ * Used by the Node.js wrapper for Blockly (see
+ * scripts/package/node/core.js) to supply implementations from the
+ * jsdom package instead.
+ *
+ * While they may be set individually, it is normally the case that
+ * all three will be sourced from the same JSDOM instance.  They MUST
+ * at least come from the same copy of the jsdom package.  (Typically
+ * this is hard to avoid satsifying this requirement, but it can be
+ * inadvertently violated by using webpack to build multiple bundles
+ * containing Blockly and jsdom, and then loading more than one into
+ * the same JavaScript runtime.  See
+ * https://github.com/google/blockly-samples/pull/1452#issuecomment-1364442135
+ * for an example of how this happened.)
+ *
+ * @param dependencies Options object containing dependencies to set.
+ */
+export function injectDependencies(dependencies: {
+  document?: Document;
+  DOMParser?: typeof DOMParser;
+  XMLSerializer?: typeof XMLSerializer;
+}) {
+  ({
+    // Default to existing value if option not supplied.
+    document = document,
+    DOMParser = DOMParser,
+    XMLSerializer = XMLSerializer,
+  } = dependencies);
+
+  domParser = new DOMParser();
+  xmlSerializer = new XMLSerializer();
+}
+
+/**
+ * Namespace for Blockly's XML.
+ */
+export const NAME_SPACE = 'https://developers.google.com/blockly/xml';
+
+// eslint-disable-next-line no-control-regex
+const INVALID_CONTROL_CHARS = /[\x00-\x09\x0B\x0C\x0E-\x1F]/g;
+
+/**
+ * Create DOM element for XML.
+ *
+ * @param tagName Name of DOM element.
+ * @returns New DOM element.
+ */
+export function createElement(tagName: string): Element {
+  return document.createElementNS(NAME_SPACE, tagName);
+}
+
+/**
+ * Create text element for XML.
+ *
+ * @param text Text content.
+ * @returns New DOM text node.
+ */
+export function createTextNode(text: string): Text {
+  return document.createTextNode(text);
+}
+
+/**
+ * Converts an XML string into a DOM structure.
+ *
+ * Control characters should be escaped. (But we will try to best-effort parse
+ * unescaped characters.)
+ *
+ * Note that even when escaped, U+0000 will be parsed as U+FFFD (the
+ * "replacement character") because U+0000 is never a valid XML character
+ * (even in XML 1.1).
+ * https://www.w3.org/TR/xml11/#charsets
+ *
+ * @param text An XML string.
+ * @returns A DOM object representing the singular child of the document
+ *     element.
+ * @throws if the text doesn't parse.
+ */
+export function textToDom(text: string): Element {
+  let doc = domParser.parseFromString(text, 'text/xml');
+  if (
+    doc &&
+    doc.documentElement &&
+    !doc.getElementsByTagName('parsererror').length
+  ) {
+    return doc.documentElement;
+  }
+
+  // Attempt to parse as HTML to deserialize control characters that were
+  // serialized before the serializer did proper escaping.
+  doc = domParser.parseFromString(text, 'text/html');
+  if (
+    doc &&
+    doc.body.firstChild &&
+    doc.body.firstChild.nodeName.toLowerCase() === 'xml'
+  ) {
+    return doc.body.firstChild as Element;
+  }
+
+  throw new Error(`DOMParser was unable to parse: ${text}`);
+}
+
+/**
+ * Converts a DOM structure into plain text.
+ * Currently the text format is fairly ugly: all one line with no whitespace.
+ *
+ * Control characters are escaped using their decimal encodings. This includes
+ * U+0000 even though it is technically never a valid XML character (even in
+ * XML 1.1).
+ * https://www.w3.org/TR/xml11/#charsets
+ *
+ * When decoded U+0000 will be parsed as U+FFFD (the "replacement character").
+ *
+ * @param dom A tree of XML nodes.
+ * @returns Text representation.
+ */
+export function domToText(dom: Node): string {
+  return sanitizeText(xmlSerializer.serializeToString(dom));
+}
+
+function sanitizeText(text: string) {
+  return text.replace(
+    INVALID_CONTROL_CHARS,
+    (match) => `&#${match.charCodeAt(0)};`,
+  );
+}