blockly 8.0.5 → 9.0.0-beta.0

package/core/keyboard_nav/basic_cursor.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ASTNode } from './ast_node.js';
+import { Cursor } from './cursor.js';
+/**
+ * Class for a basic cursor.
+ * This will allow the user to get to all nodes in the AST by hitting next or
+ * previous.
+ * @alias Blockly.BasicCursor
+ */
+export declare class BasicCursor extends Cursor {
+    /** Name used for registering a basic cursor. */
+    static readonly registrationName = "basicCursor";
+    /** @alias Blockly.BasicCursor */
+    constructor();
+    /**
+     * Find the next node in the pre order traversal.
+     * @return The next node, or null if the current node is not set or there is
+     *     no next value.
+     */
+    next(): ASTNode | null;
+    /**
+     * For a basic cursor we only have the ability to go next and previous, so
+     * in will also allow the user to get to the next node in the pre order
+     * traversal.
+     * @return The next node, or null if the current node is not set or there is
+     *     no next value.
+     */
+    in(): ASTNode | null;
+    /**
+     * Find the previous node in the pre order traversal.
+     * @return The previous node, or null if the current node is not set or there
+     *     is no previous value.
+     */
+    prev(): ASTNode | null;
+    /**
+     * For a basic cursor we only have the ability to go next and previous, so
+     * out will allow the user to get to the previous node in the pre order
+     * traversal.
+     * @return The previous node, or null if the current node is not set or there
+     *     is no previous value.
+     */
+    out(): ASTNode | null;
+    /**
+     * Uses pre order traversal to navigate the Blockly AST. This will allow
+     * a user to easily navigate the entire Blockly AST without having to go in
+     * and out levels on the tree.
+     * @param node The current position in the AST.
+     * @param isValid A function true/false depending on whether the given node
+     *     should be traversed.
+     * @return The next node in the traversal.
+     */
+    protected getNextNode_(node: ASTNode | null, isValid: (p1: ASTNode | null) => boolean): ASTNode | null;
+    /**
+     * Reverses the pre order traversal in order to find the previous node. This
+     * will allow a user to easily navigate the entire Blockly AST without having
+     * to go in and out levels on the tree.
+     * @param node The current position in the AST.
+     * @param isValid A function true/false depending on whether the given node
+     *     should be traversed.
+     * @return The previous node in the traversal or null if no previous node
+     *     exists.
+     */
+    protected getPreviousNode_(node: ASTNode | null, isValid: (p1: ASTNode | null) => boolean): ASTNode | null;
+    /**
+     * Decides what nodes to traverse and which ones to skip. Currently, it
+     * skips output, stack and workspace nodes.
+     * @param node The AST node to check whether it is valid.
+     * @return True if the node should be visited, false otherwise.
+     */
+    protected validNode_(node: ASTNode | null): boolean;
+    /**
+     * From the given node find either the next valid sibling or parent.
+     * @param node The current position in the AST.
+     * @return The parent AST node or null if there are no valid parents.
+     */
+    private findSiblingOrParent_;
+    /**
+     * Get the right most child of a node.
+     * @param node The node to find the right most child of.
+     * @return The right most child of the given node, or the node if no child
+     *     exists.
+     */
+    private getRightMostChild_;
+}

package/core/keyboard_nav/{basic_cursor.js → basic_cursor.ts}

@@ -8,42 +8,42 @@
  * @fileoverview The class representing a basic cursor.
  * Used to demo switching between different cursors.
  */
-'use strict';
 
 /**
  * The class representing a basic cursor.
  * Used to demo switching between different cursors.
  * @class
  */
-goog.module('Blockly.BasicCursor');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.BasicCursor');
 
-const registry = goog.require('Blockly.registry');
-const {ASTNode} = goog.require('Blockly.ASTNode');
-const {Cursor} = goog.require('Blockly.Cursor');
+import * as registry from '../registry.js';
+
+import {ASTNode} from './ast_node.js';
+import {Cursor} from './cursor.js';
 
 
 /**
  * Class for a basic cursor.
  * This will allow the user to get to all nodes in the AST by hitting next or
  * previous.
- * @extends {Cursor}
  * @alias Blockly.BasicCursor
  */
-class BasicCursor extends Cursor {
-  /**
-   * @alias Blockly.BasicCursor
-   */
+export class BasicCursor extends Cursor {
+  /** Name used for registering a basic cursor. */
+  static readonly registrationName = 'basicCursor';
+
+  /** @alias Blockly.BasicCursor */
   constructor() {
     super();
   }
 
   /**
    * Find the next node in the pre order traversal.
-   * @return {?ASTNode} The next node, or null if the current node is
-   *     not set or there is no next value.
-   * @override
+   * @return The next node, or null if the current node is not set or there is
+   *     no next value.
    */
-  next() {
+  override next(): ASTNode|null {
     const curNode = this.getCurNode();
     if (!curNode) {
       return null;
@@ -60,21 +60,19 @@ class BasicCursor extends Cursor {
    * For a basic cursor we only have the ability to go next and previous, so
    * in will also allow the user to get to the next node in the pre order
    * traversal.
-   * @return {?ASTNode} The next node, or null if the current node is
-   *     not set or there is no next value.
-   * @override
+   * @return The next node, or null if the current node is not set or there is
+   *     no next value.
    */
-  in() {
+  override in(): ASTNode|null {
     return this.next();
   }
 
   /**
    * Find the previous node in the pre order traversal.
-   * @return {?ASTNode} The previous node, or null if the current node
-   *     is not set or there is no previous value.
-   * @override
+   * @return The previous node, or null if the current node is not set or there
+   *     is no previous value.
    */
-  prev() {
+  override prev(): ASTNode|null {
     const curNode = this.getCurNode();
     if (!curNode) {
       return null;
@@ -91,11 +89,10 @@ class BasicCursor extends Cursor {
    * For a basic cursor we only have the ability to go next and previous, so
    * out will allow the user to get to the previous node in the pre order
    * traversal.
-   * @return {?ASTNode} The previous node, or null if the current node is
-   *     not set or there is no previous value.
-   * @override
+   * @return The previous node, or null if the current node is not set or there
+   *     is no previous value.
    */
-  out() {
+  override out(): ASTNode|null {
     return this.prev();
   }
 
@@ -103,13 +100,14 @@ class BasicCursor extends Cursor {
    * Uses pre order traversal to navigate the Blockly AST. This will allow
    * a user to easily navigate the entire Blockly AST without having to go in
    * and out levels on the tree.
-   * @param {?ASTNode} node The current position in the AST.
-   * @param {!function(ASTNode) : boolean} isValid A function true/false
-   *     depending on whether the given node should be traversed.
-   * @return {?ASTNode} The next node in the traversal.
-   * @protected
+   * @param node The current position in the AST.
+   * @param isValid A function true/false depending on whether the given node
+   *     should be traversed.
+   * @return The next node in the traversal.
    */
-  getNextNode_(node, isValid) {
+  protected getNextNode_(
+      node: ASTNode|null, isValid: (p1: ASTNode|null) => boolean): ASTNode
+      |null {
     if (!node) {
       return null;
     }
@@ -120,7 +118,9 @@ class BasicCursor extends Cursor {
       return this.getNextNode_(newNode, isValid);
     }
     const siblingOrParent = this.findSiblingOrParent_(node.out());
-    if (isValid(siblingOrParent)) {
+    // AnyDuringMigration because:  Argument of type 'ASTNode | null' is not
+    // assignable to parameter of type 'ASTNode'.
+    if (isValid(siblingOrParent as AnyDuringMigration)) {
       return siblingOrParent;
     } else if (siblingOrParent) {
       return this.getNextNode_(siblingOrParent, isValid);
@@ -132,18 +132,19 @@ class BasicCursor extends Cursor {
    * Reverses the pre order traversal in order to find the previous node. This
    * will allow a user to easily navigate the entire Blockly AST without having
    * to go in and out levels on the tree.
-   * @param {?ASTNode} node The current position in the AST.
-   * @param {!function(ASTNode) : boolean} isValid A function true/false
-   *     depending on whether the given node should be traversed.
-   * @return {?ASTNode} The previous node in the traversal or null if no
-   *     previous node exists.
-   * @protected
+   * @param node The current position in the AST.
+   * @param isValid A function true/false depending on whether the given node
+   *     should be traversed.
+   * @return The previous node in the traversal or null if no previous node
+   *     exists.
    */
-  getPreviousNode_(node, isValid) {
+  protected getPreviousNode_(
+      node: ASTNode|null, isValid: (p1: ASTNode|null) => boolean): ASTNode
+      |null {
     if (!node) {
       return null;
     }
-    let newNode = node.prev();
+    let newNode: ASTNode|null = node.prev();
 
     if (newNode) {
       newNode = this.getRightMostChild_(newNode);
@@ -161,11 +162,10 @@ class BasicCursor extends Cursor {
   /**
    * Decides what nodes to traverse and which ones to skip. Currently, it
    * skips output, stack and workspace nodes.
-   * @param {?ASTNode} node The AST node to check whether it is valid.
-   * @return {boolean} True if the node should be visited, false otherwise.
-   * @protected
+   * @param node The AST node to check whether it is valid.
+   * @return True if the node should be visited, false otherwise.
    */
-  validNode_(node) {
+  protected validNode_(node: ASTNode|null): boolean {
     let isValid = false;
     const type = node && node.getType();
     if (type === ASTNode.types.OUTPUT || type === ASTNode.types.INPUT ||
@@ -178,12 +178,10 @@ class BasicCursor extends Cursor {
 
   /**
    * From the given node find either the next valid sibling or parent.
-   * @param {?ASTNode} node The current position in the AST.
-   * @return {?ASTNode} The parent AST node or null if there are no
-   *     valid parents.
-   * @private
+   * @param node The current position in the AST.
+   * @return The parent AST node or null if there are no valid parents.
    */
-  findSiblingOrParent_(node) {
+  private findSiblingOrParent_(node: ASTNode|null): ASTNode|null {
     if (!node) {
       return null;
     }
@@ -196,30 +194,21 @@ class BasicCursor extends Cursor {
 
   /**
    * Get the right most child of a node.
-   * @param {?ASTNode} node The node to find the right most child of.
-   * @return {?ASTNode} The right most child of the given node, or the node
-   *     if no child exists.
-   * @private
+   * @param node The node to find the right most child of.
+   * @return The right most child of the given node, or the node if no child
+   *     exists.
    */
-  getRightMostChild_(node) {
-    if (!node.in()) {
+  private getRightMostChild_(node: ASTNode|null): ASTNode|null {
+    if (!node!.in()) {
       return node;
     }
-    let newNode = node.in();
-    while (newNode.next()) {
+    let newNode = node!.in();
+    while (newNode && newNode.next()) {
       newNode = newNode.next();
     }
     return this.getRightMostChild_(newNode);
   }
 }
 
-/**
- * Name used for registering a basic cursor.
- * @const {string}
- */
-BasicCursor.registrationName = 'basicCursor';
-
 registry.register(
     registry.Type.CURSOR, BasicCursor.registrationName, BasicCursor);
-
-exports.BasicCursor = BasicCursor;

package/core/keyboard_nav/cursor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ASTNode } from './ast_node.js';
+import { Marker } from './marker.js';
+/**
+ * Class for a cursor.
+ * A cursor controls how a user navigates the Blockly AST.
+ * @alias Blockly.Cursor
+ */
+export declare class Cursor extends Marker {
+    type: string;
+    /** @alias Blockly.Cursor */
+    constructor();
+    /**
+     * Find the next connection, field, or block.
+     * @return The next element, or null if the current node is not set or there
+     *     is no next value.
+     */
+    next(): ASTNode | null;
+    /**
+     * Find the in connection or field.
+     * @return The in element, or null if the current node is not set or there is
+     *     no in value.
+     */
+    in(): ASTNode | null;
+    /**
+     * Find the previous connection, field, or block.
+     * @return The previous element, or null if the current node is not set or
+     *     there is no previous value.
+     */
+    prev(): ASTNode | null;
+    /**
+     * Find the out connection, field, or block.
+     * @return The out element, or null if the current node is not set or there is
+     *     no out value.
+     */
+    out(): ASTNode | null;
+}

package/core/keyboard_nav/{cursor.js → cursor.ts}

@@ -8,45 +8,40 @@
  * @fileoverview The class representing a cursor.
  * Used primarily for keyboard navigation.
  */
-'use strict';
 
 /**
  * The class representing a cursor.
  * Used primarily for keyboard navigation.
  * @class
  */
-goog.module('Blockly.Cursor');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Cursor');
+
+import * as registry from '../registry.js';
+
+import {ASTNode} from './ast_node.js';
+import {Marker} from './marker.js';
 
-const registry = goog.require('Blockly.registry');
-const {ASTNode} = goog.require('Blockly.ASTNode');
-const {Marker} = goog.require('Blockly.Marker');
 
 /**
  * Class for a cursor.
  * A cursor controls how a user navigates the Blockly AST.
- * @extends {Marker}
  * @alias Blockly.Cursor
  */
-class Cursor extends Marker {
-  /**
-   * @alias Blockly.Cursor
-   */
+export class Cursor extends Marker {
+  override type = 'cursor';
+
+  /** @alias Blockly.Cursor */
   constructor() {
     super();
-
-    /**
-     * @override
-     */
-    this.type = 'cursor';
   }
 
   /**
    * Find the next connection, field, or block.
-   * @return {ASTNode} The next element, or null if the current node is
-   *     not set or there is no next value.
-   * @public
+   * @return The next element, or null if the current node is not set or there
+   *     is no next value.
    */
-  next() {
+  next(): ASTNode|null {
     const curNode = this.getCurNode();
     if (!curNode) {
       return null;
@@ -67,12 +62,11 @@ class Cursor extends Marker {
 
   /**
    * Find the in connection or field.
-   * @return {ASTNode} The in element, or null if the current node is
-   *     not set or there is no in value.
-   * @public
+   * @return The in element, or null if the current node is not set or there is
+   *     no in value.
    */
-  in() {
-    let curNode = this.getCurNode();
+  in(): ASTNode|null {
+    let curNode: ASTNode|null = this.getCurNode();
     if (!curNode) {
       return null;
     }
@@ -82,7 +76,7 @@ class Cursor extends Marker {
         curNode.getType() === ASTNode.types.OUTPUT) {
       curNode = curNode.next();
     }
-    const newNode = curNode.in();
+    const newNode = curNode?.in() ?? null;
 
     if (newNode) {
       this.setCurNode(newNode);
@@ -92,11 +86,10 @@ class Cursor extends Marker {
 
   /**
    * Find the previous connection, field, or block.
-   * @return {ASTNode} The previous element, or null if the current node
-   *     is not set or there is no previous value.
-   * @public
+   * @return The previous element, or null if the current node is not set or
+   *     there is no previous value.
    */
-  prev() {
+  prev(): ASTNode|null {
     const curNode = this.getCurNode();
     if (!curNode) {
       return null;
@@ -117,11 +110,10 @@ class Cursor extends Marker {
 
   /**
    * Find the out connection, field, or block.
-   * @return {ASTNode} The out element, or null if the current node is
-   *     not set or there is no out value.
-   * @public
+   * @return The out element, or null if the current node is not set or there is
+   *     no out value.
    */
-  out() {
+  out(): ASTNode|null {
     const curNode = this.getCurNode();
     if (!curNode) {
       return null;
@@ -140,5 +132,3 @@ class Cursor extends Marker {
 }
 
 registry.register(registry.Type.CURSOR, registry.DEFAULT, Cursor);
-
-exports.Cursor = Cursor;

package/core/keyboard_nav/marker.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { MarkerSvg } from '../renderers/common/marker_svg.js';
+import type { ASTNode } from './ast_node.js';
+/**
+ * Class for a marker.
+ * This is used in keyboard navigation to save a location in the Blockly AST.
+ * @alias Blockly.Marker
+ */
+export declare class Marker {
+    /** The colour of the marker. */
+    colour: string | null;
+    /** The current location of the marker. */
+    private curNode_;
+    /**
+     * The object in charge of drawing the visual representation of the current
+     * node.
+     */
+    private drawer_;
+    /** The type of the marker. */
+    type: string;
+    /** Constructs a new Marker instance. */
+    constructor();
+    /**
+     * Sets the object in charge of drawing the marker.
+     * @param drawer The object in charge of drawing the marker.
+     */
+    setDrawer(drawer: MarkerSvg): void;
+    /**
+     * Get the current drawer for the marker.
+     * @return The object in charge of drawing the marker.
+     */
+    getDrawer(): MarkerSvg;
+    /**
+     * Gets the current location of the marker.
+     * @return The current field, connection, or block the marker is on.
+     */
+    getCurNode(): ASTNode;
+    /**
+     * Set the location of the marker and call the update method.
+     * Setting isStack to true will only work if the newLocation is the top most
+     * output or previous connection on a stack.
+     * @param newNode The new location of the marker.
+     */
+    setCurNode(newNode: ASTNode): void;
+    /**
+     * Redraw the current marker.
+     * @internal
+     */
+    draw(): void;
+    /** Hide the marker SVG. */
+    hide(): void;
+    /** Dispose of this marker. */
+    dispose(): void;
+}