blockly 12.4.0 → 12.5.0

package/core/renderers/common/i_path_object.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../../block_svg.js';
+import type { RenderedConnection } from '../../rendered_connection.js';
+import type { BlockStyle } from '../../theme.js';
+import type { Coordinate } from '../../utils/coordinate.js';
+import type { ConstantProvider } from './constants.js';
+/**
+ * An interface for a block's path object.
+ *
+ * @param _root The root SVG element.
+ * @param _constants The renderer's constants.
+ */
+export interface IPathObject {
+    /**
+     * The primary path of the block.
+     */
+    svgPath: SVGElement;
+    /** The renderer's constant provider. */
+    constants: ConstantProvider;
+    /** The primary path of the block. */
+    style: BlockStyle;
+    /**
+     * Set the path generated by the renderer onto the respective SVG element.
+     *
+     * @param pathString The path.
+     */
+    setPath(pathString: string): void;
+    /**
+     * Flip the SVG paths in RTL.
+     */
+    flipRTL(): void;
+    /**
+     * Set whether the block shows a highlight or not.  Block highlighting is
+     * often used to visually mark blocks currently being executed.
+     *
+     * @param highlighted True if highlighted.
+     */
+    updateHighlighted(highlighted: boolean): void;
+    /**
+     * Add or remove styling showing that a block is selected.
+     *
+     * @param enable True if selection is enabled, false otherwise.
+     */
+    updateSelected(enabled: boolean): void;
+    /**
+     * Add or remove styling showing that a block is dragged over a delete area.
+     *
+     * @param enable True if the block is being dragged over a delete area, false
+     *     otherwise.
+     */
+    updateDraggingDelete(enabled: boolean): void;
+    /**
+     * Add or remove styling showing that a block is an insertion marker.
+     *
+     * @param enable True if the block is an insertion marker, false otherwise.
+     */
+    updateInsertionMarker(enabled: boolean): void;
+    /**
+     * Add or remove styling showing that a block is movable.
+     *
+     * @param enable True if the block is movable, false otherwise.
+     */
+    updateMovable(enabled: boolean): void;
+    /** Adds the given path as a connection highlight for the given connection. */
+    addConnectionHighlight?(connection: RenderedConnection, connectionPath: string, offset: Coordinate, rtl: boolean): SVGElement;
+    /**
+     * Apply the stored colours to the block's path, taking into account whether
+     * the paths belong to a shadow block.
+     *
+     * @param block The source block.
+     */
+    applyColour?(block: BlockSvg): void;
+    /**
+     * Removes any highlight associated with the given connection, if it exists.
+     */
+    removeConnectionHighlight?(connection: RenderedConnection): void;
+    /**
+     * Update the style.
+     *
+     * @param blockStyle The block style to use.
+     */
+    setStyle?(blockStyle: BlockStyle): void;
+}
+//# sourceMappingURL=i_path_object.d.ts.map

package/core/renderers/common/info.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../../block_svg.js';
+import { Input } from '../../inputs/input.js';
+import type { RenderedConnection } from '../../rendered_connection.js';
+import type { Measurable } from '../measurables/base.js';
+import { BottomRow } from '../measurables/bottom_row.js';
+import { Connection } from '../measurables/connection.js';
+import { InputRow } from '../measurables/input_row.js';
+import { OutputConnection } from '../measurables/output_connection.js';
+import type { Row } from '../measurables/row.js';
+import { SpacerRow } from '../measurables/spacer_row.js';
+import { TopRow } from '../measurables/top_row.js';
+import type { ConstantProvider } from './constants.js';
+import type { Renderer } from './renderer.js';
+/**
+ * An object containing all sizing information needed to draw this block.
+ *
+ * This measure pass does not propagate changes to the block (although fields
+ * may choose to rerender when getSize() is called).  However, calling it
+ * repeatedly may be expensive.
+ */
+export declare class RenderInfo {
+    block_: BlockSvg;
+    protected constants_: ConstantProvider;
+    outputConnection: OutputConnection | null;
+    isInline: boolean;
+    isCollapsed: boolean;
+    isInsertionMarker: boolean;
+    RTL: boolean;
+    /** The block renderer in use. */
+    protected readonly renderer_: Renderer;
+    /** The height of the rendered block, including child blocks. */
+    height: number;
+    /** The width of the rendered block, including child blocks. */
+    widthWithChildren: number;
+    /**
+     * The width of the rendered block, excluding child blocks.  This is the
+     * right edge of the block when rendered LTR.
+     */
+    width: number;
+    statementEdge: number;
+    /** An array of Row objects containing sizing information. */
+    rows: Row[];
+    /** An array of input rows on the block. */
+    inputRows: InputRow[];
+    topRow: TopRow;
+    bottomRow: BottomRow;
+    startX: number;
+    startY: number;
+    /**
+     * @param renderer The renderer in use.
+     * @param block The block to measure.
+     */
+    constructor(renderer: Renderer, block: BlockSvg);
+    /**
+     * Get the block renderer in use.
+     *
+     * @returns The block renderer in use.
+     */
+    getRenderer(): Renderer;
+    /**
+     * Populate this object with all sizing information needed to draw the block.
+     *
+     * This measure pass does not propagate changes to the block (although fields
+     * may choose to rerender when getSize() is called).  However, calling it
+     * repeatedly may be expensive.
+     */
+    measure(): void;
+    /**
+     * Create rows of Measurable objects representing all renderable parts of the
+     * block.
+     */
+    protected createRows_(): void;
+    /**
+     * Create all non-spacer elements that belong on the top row.
+     */
+    protected populateTopRow_(): void;
+    /**
+     * Create all non-spacer elements that belong on the bottom row.
+     */
+    protected populateBottomRow_(): void;
+    /**
+     * Add an input element to the active row, if needed, and record the type of
+     * the input on the row.
+     *
+     * @param input The input to record information about.
+     * @param activeRow The row that is currently being populated.
+     */
+    protected addInput_(input: Input, activeRow: Row): void;
+    /**
+     * Decide whether to start a new row between the two Blockly.Inputs.
+     *
+     * @param currInput The current input.
+     * @param prevInput The previous input.
+     * @returns True if the current input should be rendered on a new row.
+     */
+    protected shouldStartNewRow_(currInput: Input, prevInput?: Input): boolean;
+    /** Add horizontal spacing between and around elements within each row. */
+    protected addElemSpacing_(): void;
+    /**
+     * Calculate the width of a spacer element in a row based on the previous and
+     * next elements in that row.  For instance, extra padding is added between
+     * two editable fields.
+     *
+     * @param prev The element before the spacer.
+     * @param next The element after the spacer.
+     * @returns The size of the spacing between the two elements.
+     */
+    protected getInRowSpacing_(prev: Measurable | null, next: Measurable | null): number;
+    /**
+     * Figure out where the right edge of the block and right edge of statement
+     * inputs should be placed.
+     */
+    protected computeBounds_(): void;
+    /**
+     * Extra spacing may be necessary to make sure that the right sides of all
+     * rows line up.  This can only be calculated after a first pass to calculate
+     * the sizes of all rows.
+     */
+    protected alignRowElements_(): void;
+    /**
+     * Calculate the desired width of an input row.
+     *
+     * @param _row The input row.
+     * @returns The desired width of the input row.
+     */
+    protected getDesiredRowWidth_(_row: Row): number;
+    /**
+     * Modify the given row to add the given amount of padding around its fields.
+     * The exact location of the padding is based on the alignment property of the
+     * last input in the field.
+     *
+     * @param row The row to add padding to.
+     * @param missingSpace How much padding to add.
+     */
+    protected addAlignmentPadding_(row: Row, missingSpace: number): void;
+    /**
+     * Align the elements of a statement row based on computed bounds.
+     * Unlike other types of rows, statement rows add space in multiple places.
+     *
+     * @param row The statement row to resize.
+     */
+    protected alignStatementRow_(row: InputRow): void;
+    /** Add spacers between rows and set their sizes. */
+    protected addRowSpacing_(): void;
+    /**
+     * Create a spacer row to go between prev and next, and set its size.
+     *
+     * @param prev The previous row.
+     * @param next The next row.
+     * @returns The newly created spacer row.
+     */
+    protected makeSpacerRow_(prev: Row, next: Row): SpacerRow;
+    /**
+     * Calculate the width of a spacer row.
+     *
+     * @param _prev The row before the spacer.
+     * @param _next The row after the spacer.
+     * @returns The desired width of the spacer row between these two rows.
+     */
+    protected getSpacerRowWidth_(_prev: Row, _next: Row): number;
+    /**
+     * Calculate the height of a spacer row.
+     *
+     * @param _prev The row before the spacer.
+     * @param _next The row after the spacer.
+     * @returns The desired height of the spacer row between these two rows.
+     */
+    protected getSpacerRowHeight_(_prev: Row, _next: Row): number;
+    /**
+     * Calculate the centerline of an element in a rendered row.
+     * This base implementation puts the centerline at the middle of the row
+     * vertically, with no special cases.  You will likely need extra logic to
+     * handle (at minimum) top and bottom rows.
+     *
+     * @param row The row containing the element.
+     * @param elem The element to place.
+     * @returns The desired centerline of the given element, as an offset from the
+     *     top left of the block.
+     */
+    protected getElemCenterline_(row: Row, elem: Measurable): number;
+    /**
+     * Record final position information on elements on the given row, for use in
+     * drawing.  At minimum this records xPos and centerline on each element.
+     *
+     * @param row The row containing the elements.
+     */
+    protected recordElemPositions_(row: Row): void;
+    /**
+     * Make any final changes to the rendering information object.  In particular,
+     * store the y position of each row, and record the height of the full block.
+     */
+    protected finalize_(): void;
+    /** Returns the connection measurable associated with the given connection. */
+    getMeasureableForConnection(conn: RenderedConnection): Connection | null;
+}
+//# sourceMappingURL=info.d.ts.map

package/core/renderers/common/path_object.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../../block_svg.js';
+import type { Connection } from '../../connection.js';
+import { RenderedConnection } from '../../rendered_connection.js';
+import type { BlockStyle } from '../../theme.js';
+import { Coordinate } from '../../utils/coordinate.js';
+import type { ConstantProvider } from './constants.js';
+import type { IPathObject } from './i_path_object.js';
+/**
+ * An object that handles creating and setting each of the SVG elements
+ * used by the renderer.
+ */
+export declare class PathObject implements IPathObject {
+    svgRoot: SVGElement;
+    svgPath: SVGElement;
+    constants: ConstantProvider;
+    style: BlockStyle;
+    /** Highlight paths associated with connections. */
+    private connectionHighlights;
+    /** Locations of connection highlights. */
+    private highlightOffsets;
+    /**
+     * @param root The root SVG element.
+     * @param style The style object to use for colouring.
+     * @param constants The renderer's constants.
+     */
+    constructor(root: SVGElement, style: BlockStyle, constants: ConstantProvider);
+    /**
+     * Set the path generated by the renderer onto the respective SVG element.
+     *
+     * @param pathString The path.
+     */
+    setPath(pathString: string): void;
+    /**
+     * Flip the SVG paths in RTL.
+     */
+    flipRTL(): void;
+    /**
+     * Apply the stored colours to the block's path, taking into account whether
+     * the paths belong to a shadow block.
+     *
+     * @param block The source block.
+     */
+    applyColour(block: BlockSvg): void;
+    /**
+     * Set the style.
+     *
+     * @param blockStyle The block style to use.
+     */
+    setStyle(blockStyle: BlockStyle): void;
+    /**
+     * Add or remove the given CSS class on the path object's root SVG element.
+     *
+     * @param className The name of the class to add or remove
+     * @param add True if the class should be added.  False if it should be
+     *     removed.
+     */
+    protected setClass_(className: string, add: boolean): void;
+    /**
+     * Set whether the block shows a highlight or not.  Block highlighting is
+     * often used to visually mark blocks currently being executed.
+     *
+     * @param enable True if highlighted.
+     */
+    updateHighlighted(enable: boolean): void;
+    /**
+     * Updates the look of the block to reflect a shadow state.
+     *
+     * @param shadow True if the block is a shadow block.
+     */
+    protected updateShadow_(shadow: boolean): void;
+    /**
+     * Updates the look of the block to reflect a disabled state.
+     *
+     * @param disabled True if disabled.
+     */
+    protected updateDisabled_(disabled: boolean): void;
+    /**
+     * Add or remove styling showing that a block is selected.
+     *
+     * @param enable True if selection is enabled, false otherwise.
+     */
+    updateSelected(enable: boolean): void;
+    /**
+     * Add or remove styling showing that a block is dragged over a delete area.
+     *
+     * @param enable True if the block is being dragged over a delete area, false
+     *     otherwise.
+     */
+    updateDraggingDelete(enable: boolean): void;
+    /**
+     * Add or remove styling showing that a block is an insertion marker.
+     *
+     * @param enable True if the block is an insertion marker, false otherwise.
+     */
+    updateInsertionMarker(enable: boolean): void;
+    /**
+     * Add or remove styling showing that a block is movable.
+     *
+     * @param enable True if the block is movable, false otherwise.
+     */
+    updateMovable(enable: boolean): void;
+    /**
+     * Add or remove styling that shows that if the dragging block is dropped,
+     * this block will be replaced.  If a shadow block, it will disappear.
+     * Otherwise it will bump.
+     *
+     * @param enable True if styling should be added.
+     */
+    updateReplacementFade(enable: boolean): void;
+    /**
+     * Add or remove styling that shows that if the dragging block is dropped,
+     * this block will be connected to the input.
+     *
+     * @param _conn The connection on the input to highlight.
+     * @param _enable True if styling should be added.
+     */
+    updateShapeForInputHighlight(_conn: Connection, _enable: boolean): void;
+    /** Adds the given path as a connection highlight for the given connection. */
+    addConnectionHighlight(connection: RenderedConnection, connectionPath: string, offset: Coordinate, rtl: boolean): SVGElement;
+    /**
+     * Removes any highlight associated with the given connection, if it exists.
+     */
+    removeConnectionHighlight(connection: RenderedConnection): void;
+}
+//# sourceMappingURL=path_object.d.ts.map

package/core/renderers/common/renderer.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../../block_svg.js';
+import { Connection } from '../../connection.js';
+import type { IRegistrable } from '../../interfaces/i_registrable.js';
+import type { BlockStyle, Theme } from '../../theme.js';
+import { ConstantProvider } from './constants.js';
+import { Drawer } from './drawer.js';
+import type { IPathObject } from './i_path_object.js';
+import { RenderInfo } from './info.js';
+/**
+ * The base class for a block renderer.
+ */
+export declare class Renderer implements IRegistrable {
+    /** The renderer's constant provider. */
+    protected constants_: ConstantProvider;
+    protected name: string;
+    /**
+     * Rendering constant overrides, passed in through options.
+     */
+    protected overrides: object | null;
+    /**
+     * @param name The renderer name.
+     */
+    constructor(name: string);
+    /**
+     * Gets the class name that identifies this renderer.
+     *
+     * @returns The CSS class name.
+     */
+    getClassName(): string;
+    /**
+     * Initialize the renderer.
+     *
+     * @param theme The workspace theme object.
+     * @param opt_rendererOverrides Rendering constant overrides.
+     */
+    init(theme: Theme, opt_rendererOverrides?: {
+        [rendererConstant: string]: any;
+    }): void;
+    /**
+     * Create any DOM elements that this renderer needs.
+     * If you need to create additional DOM elements, override the
+     * {@link blockRendering#ConstantProvider.createDom} method instead.
+     *
+     * @param svg The root of the workspace's SVG.
+     * @param theme The workspace theme object.
+     * @param injectionDivIfIsParent The div containing the parent workspace and
+     *   all related workspaces and block containers, if this renderer is for the
+     *   parent workspace. CSS variables representing SVG patterns will be scoped
+     *   to this container. Child workspaces should not override the CSS variables
+     *   created by the parent and thus do not need access to the injection div.
+     * @internal
+     */
+    createDom(svg: SVGElement, theme: Theme, injectionDivIfIsParent?: HTMLElement): void;
+    /**
+     * Refresh the renderer after a theme change.
+     *
+     * @param svg The root of the workspace's SVG.
+     * @param theme The workspace theme object.
+     * @param injectionDivIfIsParent The div containing the parent workspace and
+     *   all related workspaces and block containers, if this renderer is for the
+     *   parent workspace. CSS variables representing SVG patterns will be scoped
+     *   to this container. Child workspaces should not override the CSS variables
+     *   created by the parent and thus do not need access to the injection div.
+     */
+    refreshDom(svg: SVGElement, theme: Theme, injectionDivIfIsParent?: HTMLElement): void;
+    /**
+     * Dispose of this renderer.
+     * Delete all DOM elements that this renderer and its constants created.
+     */
+    dispose(): void;
+    /**
+     * Create a new instance of the renderer's constant provider.
+     *
+     * @returns The constant provider.
+     */
+    protected makeConstants_(): ConstantProvider;
+    /**
+     * Create a new instance of the renderer's render info object.
+     *
+     * @param block The block to measure.
+     * @returns The render info object.
+     */
+    protected makeRenderInfo_(block: BlockSvg): RenderInfo;
+    /**
+     * Create a new instance of the renderer's drawer.
+     *
+     * @param block The block to render.
+     * @param info An object containing all information needed to render this
+     *     block.
+     * @returns The drawer.
+     */
+    protected makeDrawer_(block: BlockSvg, info: RenderInfo): Drawer;
+    /**
+     * Create a new instance of a renderer path object.
+     *
+     * @param root The root SVG element.
+     * @param style The style object to use for colouring.
+     * @returns The renderer path object.
+     */
+    makePathObject(root: SVGElement, style: BlockStyle): IPathObject;
+    /**
+     * Get the current renderer's constant provider.  We assume that when this is
+     * called, the renderer has already been initialized.
+     *
+     * @returns The constant provider.
+     */
+    getConstants(): ConstantProvider;
+    /**
+     * Determine whether or not to highlight a connection.
+     *
+     * @param _conn The connection to determine whether or not to highlight.
+     * @returns True if we should highlight the connection.
+     */
+    shouldHighlightConnection(_conn: Connection): boolean;
+    /**
+     * Checks if an orphaned block can connect to the "end" of the topBlock's
+     * block-clump. If the clump is a row the end is the last input. If the clump
+     * is a stack, the end is the last next connection. If the clump is neither,
+     * then this returns false.
+     *
+     * @param topBlock The top block of the block clump we want to try and connect
+     *     to.
+     * @param orphanBlock The orphan block that wants to find a home.
+     * @param localType The type of the connection being dragged.
+     * @returns Whether there is a home for the orphan or not.
+     */
+    protected orphanCanConnectAtEnd(topBlock: BlockSvg, orphanBlock: BlockSvg, localType: number): boolean;
+    /**
+     * Render the block.
+     *
+     * @param block The block to render.
+     * @internal
+     */
+    render(block: BlockSvg): void;
+}
+//# sourceMappingURL=renderer.d.ts.map

package/core/renderers/geras/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ConstantProvider as BaseConstantProvider } from '../common/constants.js';
+/**
+ * An object that provides constants for rendering blocks in Geras mode.
+ */
+export declare class ConstantProvider extends BaseConstantProvider {
+    FIELD_TEXT_BASELINE_CENTER: boolean;
+    DARK_PATH_OFFSET: number;
+    /**
+     * The maximum width of a bottom row that follows a statement input and has
+     * inputs inline.
+     */
+    MAX_BOTTOM_WIDTH: number;
+    STATEMENT_BOTTOM_SPACER: number;
+    constructor();
+    getCSS_(selector: string): string[];
+}
+//# sourceMappingURL=constants.d.ts.map

package/core/renderers/geras/drawer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../../block_svg.js';
+import { Drawer as BaseDrawer } from '../common/drawer.js';
+import type { Row } from '../measurables/row.js';
+import type { ConstantProvider } from './constants.js';
+import { Highlighter } from './highlighter.js';
+import type { RenderInfo } from './info.js';
+import type { InlineInput } from './measurables/inline_input.js';
+/**
+ * An object that draws a block based on the given rendering information,
+ * customized for the geras renderer.
+ */
+export declare class Drawer extends BaseDrawer {
+    highlighter_: Highlighter;
+    constants_: ConstantProvider;
+    /**
+     * @param block The block to render.
+     * @param info An object containing all information needed to render this
+     *     block.
+     */
+    constructor(block: BlockSvg, info: RenderInfo);
+    draw(): void;
+    drawTop_(): void;
+    drawJaggedEdge_(row: Row): void;
+    drawValueInput_(row: Row): void;
+    drawStatementInput_(row: Row): void;
+    drawRightSideRow_(row: Row): void;
+    drawBottom_(): void;
+    /**
+     * Add steps for the left side of the block, which may include an output
+     * connection
+     */
+    protected drawLeft_(): void;
+    drawInlineInput_(input: InlineInput): void;
+    positionInlineInputConnection_(input: InlineInput): void;
+    positionStatementInputConnection_(row: Row): void;
+    positionExternalValueConnection_(row: Row): void;
+    positionNextConnection_(): void;
+}
+//# sourceMappingURL=drawer.d.ts.map

package/core/renderers/geras/geras.d.ts

@@ -0,0 +1,17 @@
+/** @file Re-exports of Blockly.geras.* modules. */
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ConstantProvider } from './constants.js';
+import { Drawer } from './drawer.js';
+import { HighlightConstantProvider } from './highlight_constants.js';
+import { Highlighter } from './highlighter.js';
+import { RenderInfo } from './info.js';
+import { InlineInput } from './measurables/inline_input.js';
+import { StatementInput } from './measurables/statement_input.js';
+import { PathObject } from './path_object.js';
+import { Renderer } from './renderer.js';
+export { ConstantProvider, Drawer, HighlightConstantProvider, Highlighter, InlineInput, PathObject, Renderer, RenderInfo, StatementInput, };
+//# sourceMappingURL=geras.d.ts.map