@cp949/phyx-blockly 12.5.1-p1 → 13.4.0-patch.1

package/core/interfaces/i_draggable.d.ts

@@ -3,14 +3,20 @@
  * Copyright 2021 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Coordinate } from '../utils/coordinate';
+import type { Coordinate } from '../utils/coordinate.js';
+import type { IBoundedElement } from './i_bounded_element.js';
+import type { ISelectable } from './i_selectable.js';
+export declare enum DragDisposition {
+    COMMIT = 1,
+    DELETE = 2,
+    REVERT = 3
+}
 /**
  * Represents an object that can be dragged.
  */
-export interface IDraggable extends IDragStrategy {
+export interface IDraggable extends IDragStrategy, IBoundedElement, ISelectable {
     /**
-     * Returns the current location of the draggable in workspace
-     * coordinates.
+     * Returns the current location of the draggable in workspace coordinates.
      *
      * @returns Coordinate of current location on workspace.
      */
@@ -23,31 +29,30 @@ export interface IDragStrategy {
      * Handles any drag startup (e.g moving elements to the front of the
      * workspace).
      *
-     * @param e PointerEvent that started the drag; can be used to
-     *     check modifier keys, etc.  May be missing when dragging is
-     *     triggered programatically rather than by user.
+     * @param e Event that started the drag; can be used to check modifier keys,
+     *     etc. May be missing when dragging is triggered programmatically rather
+     *     than by user.
      */
-    startDrag(e?: PointerEvent): void;
+    startDrag(e?: PointerEvent | KeyboardEvent): IDraggable;
     /**
      * Handles moving elements to the new location, and updating any
      * visuals based on that (e.g connection previews for blocks).
      *
      * @param newLoc Workspace coordinate to which the draggable has
      *     been dragged.
-     * @param e PointerEvent that continued the drag.  Can be
-     *     used to check modifier keys, etc.
+     * @param e Event that continued the drag.  Can be used to check modifier
+     *     keys, etc.
      */
-    drag(newLoc: Coordinate, e?: PointerEvent): void;
+    drag(newLoc: Coordinate, e?: PointerEvent | KeyboardEvent): void;
     /**
-     * Handles any drag cleanup, including e.g. connecting or deleting
-     * blocks.
+     * Handles any drag cleanup, including e.g. connecting or deleting blocks.
      *
      * @param newLoc Workspace coordinate at which the drag finished.
-     *     been dragged.
-     * @param e PointerEvent that finished the drag.  Can be
-     *     used to check modifier keys, etc.
+     * @param e Event that finished the drag. Can be used to check modifier keys,
+     *     etc.
+     * @param disposition The end result of the drag.
      */
-    endDrag(e?: PointerEvent): void;
+    endDrag(e: PointerEvent | KeyboardEvent | undefined, disposition: DragDisposition): void;
     /** Moves the draggable back to where it was at the start of the drag. */
     revertDrag(): void;
 }

package/core/interfaces/i_dragger.d.ts

@@ -3,30 +3,39 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Coordinate } from '../utils/coordinate';
+import type { Coordinate } from '../utils/coordinate';
+import type { IDraggable } from './i_draggable';
 export interface IDragger {
     /**
      * Handles any drag startup.
      *
-     * @param e PointerEvent that started the drag.
+     * @param e Event that started the drag.
      */
-    onDragStart(e: PointerEvent): void;
+    onDragStart(e?: PointerEvent | KeyboardEvent): IDraggable;
     /**
      * Handles dragging, including calculating where the element should
      * actually be moved to.
      *
-     * @param e PointerEvent that continued the drag.
-     * @param totalDelta The total distance, in pixels, that the mouse
+     * @param e Event that continued the drag.
+     * @param totalDelta The total distance, in pixels, that the draggable
      *     has moved since the start of the drag.
      */
-    onDrag(e: PointerEvent, totalDelta: Coordinate): void;
+    onDrag(e: PointerEvent | KeyboardEvent | undefined, totalDelta: Coordinate): void;
     /**
-     * Handles any drag cleanup.
+     * Handles any drag cleanup when a drag finishes normally.
      *
-     * @param e PointerEvent that finished the drag.
-     * @param totalDelta The total distance, in pixels, that the mouse
+     * @param e Event that finished the drag.
+     * @param totalDelta The total distance, in pixels, that the draggable
      *     has moved since the start of the drag.
      */
-    onDragEnd(e: PointerEvent, totalDelta: Coordinate): void;
+    onDragEnd(e: PointerEvent | KeyboardEvent | undefined, totalDelta: Coordinate): void;
+    /**
+     * Handles any drag cleanup when a drag is reverted.
+     *
+     * @param e Event that finished the drag.
+     * @param totalDelta The total distance, in pixels, that the draggable
+     *     has moved since the start of the drag.
+     */
+    onDragRevert(e: PointerEvent | KeyboardEvent | undefined, totalDelta: Coordinate): void;
 }
 //# sourceMappingURL=i_dragger.d.ts.map

package/core/interfaces/i_flyout.d.ts

@@ -3,18 +3,15 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { BlockSvg } from '../block_svg.js';
 import type { FlyoutItem } from '../flyout_item.js';
-import type { Coordinate } from '../utils/coordinate.js';
 import type { Svg } from '../utils/svg.js';
 import type { FlyoutDefinition } from '../utils/toolbox.js';
 import type { WorkspaceSvg } from '../workspace_svg.js';
-import { IFocusableTree } from './i_focusable_tree.js';
 import type { IRegistrable } from './i_registrable.js';
 /**
  * Interface for a flyout.
  */
-export interface IFlyout extends IRegistrable, IFocusableTree {
+export interface IFlyout extends IRegistrable {
     /** Whether the flyout is laid out horizontally or not. */
     horizontalLayout: boolean;
     /** Is RTL vs LTR. */
@@ -105,14 +102,6 @@ export interface IFlyout extends IRegistrable, IFocusableTree {
      * @returns List of flyout items.
      */
     getContents(): FlyoutItem[];
-    /**
-     * Create a copy of this block on the workspace.
-     *
-     * @param originalBlock The block to copy from the flyout.
-     * @returns The newly created block.
-     * @throws {Error} if something went wrong with deserialization.
-     */
-    createBlock(originalBlock: BlockSvg): BlockSvg;
     /** Reflow blocks and their mats. */
     reflow(): void;
     /**
@@ -134,25 +123,6 @@ export interface IFlyout extends IRegistrable, IFocusableTree {
     getY(): number;
     /** Position the flyout. */
     position(): void;
-    /**
-     * Determine if a drag delta is toward the workspace, based on the position
-     * and orientation of the flyout. This is used in determineDragIntention_ to
-     * determine if a new block should be created or if the flyout should scroll.
-     *
-     * @param currentDragDeltaXY How far the pointer has moved from the position
-     *     at mouse down, in pixel units.
-     * @returns True if the drag is toward the workspace.
-     */
-    isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean;
-    /**
-     * Does this flyout allow you to create a new instance of the given block?
-     * Used for deciding if a block can be "dragged out of" the flyout.
-     *
-     * @param block The block to copy from the flyout.
-     * @returns True if you can create a new instance of the block, false
-     *     otherwise.
-     */
-    isBlockCreatable(block: BlockSvg): boolean;
     /** Scroll the flyout to the beginning of its contents. */
     scrollToStart(): void;
 }

package/core/interfaces/i_flyout_inflater.d.ts

@@ -7,6 +7,15 @@ export interface IFlyoutInflater {
      * Note that this method's interface is identical to that in ISerializer, to
      * allow for code reuse.
      *
+     * You must ensure that any item created by this method has the appropriate
+     * ARIA markup:
+     * - The role of the element's focusable element should be set to `listitem`.
+     * - The focusable element must have an `id` attribute.
+     * - Any DOM parents of the focusable element should set their role to
+     *   `presentation` to avoid interfering with flyout list navigation.
+     * - If the element is not focusable, it must be hidden from the ARIA tree.
+     *   Only do this if the content should be inaccessible to screenreaders.
+     *
      * @param state A JSON representation of an element to inflate on the flyout.
      * @param flyout The flyout on whose workspace the inflated element
      *    should be created. If the inflated element is an `IRenderedElement` it

package/core/interfaces/i_focusable_node.d.ts

@@ -93,6 +93,14 @@ export interface IFocusableNode {
      * @returns Whether this node can be focused by FocusManager.
      */
     canBeFocused(): boolean;
+    /**
+     * Optional method invoked when this node has focus and the user acts on it by
+     * pressing Enter or Space. Behavior should generally be similar to the node
+     * being clicked on.
+     *
+     * @param e The event that triggered this action, if any.
+     */
+    performAction?(e?: Event): void;
 }
 /**
  * Determines whether the provided object fulfills the contract of

package/core/interfaces/i_focusable_tree.d.ts

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import type { Navigator } from '../keyboard_nav/navigators/navigator';
 import type { IFocusableNode } from './i_focusable_node.js';
 /**
  * Represents a tree of focusable elements with its own active/passive focus
@@ -113,6 +114,13 @@ export interface IFocusableTree {
      *     as in the case that Blockly is entirely losing DOM focus).
      */
     onTreeBlur(nextTree: IFocusableTree | null): void;
+    /**
+     * Returns a Navigator instance to be used to determine the navigation order
+     * between IFocusableNodes contained within this IFocusableTree. Generally
+     * this can just be an instance of Navigator, but trees may choose to return a
+     * subclass to customize navigation behavior within their context.
+     */
+    getNavigator(): Navigator;
 }
 /**
  * Determines whether the provided object fulfills the contract of

package/core/interfaces/i_icon.d.ts

@@ -6,7 +6,7 @@
 import type { IconType } from '../icons/icon_types.js';
 import type { Coordinate } from '../utils/coordinate.js';
 import type { Size } from '../utils/size.js';
-import { IFocusableNode } from './i_focusable_node.js';
+import type { IFocusableNode } from './i_focusable_node.js';
 export interface IIcon extends IFocusableNode {
     /**
      * @returns the IconType representing the type of the icon. This value should

package/core/interfaces/i_json_block_definition.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { FieldCheckboxFromJsonConfig } from '../field_checkbox.js';
+import type { FieldDropdownFromJsonConfig } from '../field_dropdown';
+import type { FieldImageFromJsonConfig } from '../field_image';
+import type { FieldNumberFromJsonConfig } from '../field_number';
+import type { FieldTextInputFromJsonConfig } from '../field_textinput';
+import type { FieldVariableFromJsonConfig } from '../field_variable';
+import type { Align } from '../inputs/align.js';
+/**
+ * Defines the JSON structure for a block definition.
+ *
+ * @example
+ * ```typescript
+ * const blockDef:  JsonBlockDefinition = {
+ *   type: 'custom_block',
+ *   message0: 'move %1 steps',
+ *   args0: [
+ *     {
+ *       'type': 'field_number',
+ *       'name': 'INPUT',
+ *     },
+ *   ],
+ *   previousStatement: null,
+ *   nextStatement: null,
+ * };
+ * ```
+ */
+export interface JsonBlockDefinition {
+    type: string;
+    style?: string | null;
+    colour?: string | number;
+    output?: string | string[] | null;
+    previousStatement?: string | string[] | null;
+    nextStatement?: string | string[] | null;
+    outputShape?: number;
+    inputsInline?: boolean;
+    tooltip?: string;
+    helpUrl?: string;
+    ariaRoleDescription?: string;
+    extensions?: string[];
+    mutator?: string;
+    enableContextMenu?: boolean;
+    suppressPrefixSuffix?: boolean;
+    [key: `message${number}`]: string | undefined;
+    [key: `args${number}`]: JsonBlockArg[] | undefined;
+    [key: `implicitAlign${number}`]: string | undefined;
+}
+export type JsonBlockArg = InputValueArg | InputStatementArg | InputDummyArg | InputEndRowArg | FieldInputArg | FieldNumberArg | FieldDropdownArg | FieldCheckboxArg | FieldImageArg | FieldVariableArg | UnknownArg;
+interface UnknownArg {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * A custom ARIA label for the input, used in place of the label derived from
+ * the input's preceding fields. May contain message references of the form
+ * `%{BKY_...}`, which are replaced with the corresponding `Blockly.Msg` value.
+ */
+type AriaLabelText = string;
+/** Input args */
+interface InputValueArg {
+    type: 'input_value';
+    name?: string;
+    check?: string | string[];
+    align?: Align;
+    ariaLabelText?: AriaLabelText;
+}
+interface InputStatementArg {
+    type: 'input_statement';
+    name?: string;
+    check?: string | string[];
+    ariaLabelText?: AriaLabelText;
+}
+interface InputDummyArg {
+    type: 'input_dummy';
+    name?: string;
+    ariaLabelText?: AriaLabelText;
+}
+interface InputEndRowArg {
+    type: 'input_end_row';
+    name?: string;
+    ariaLabelText?: AriaLabelText;
+}
+/** Field args */
+interface FieldInputArg extends FieldTextInputFromJsonConfig {
+    type: 'field_input';
+    name?: string;
+}
+interface FieldNumberArg extends FieldNumberFromJsonConfig {
+    type: 'field_number';
+    name?: string;
+}
+interface FieldDropdownArg extends FieldDropdownFromJsonConfig {
+    type: 'field_dropdown';
+    name?: string;
+}
+interface FieldCheckboxArg extends FieldCheckboxFromJsonConfig {
+    type: 'field_checkbox';
+    name?: string;
+}
+interface FieldImageArg extends FieldImageFromJsonConfig {
+    type: 'field_image';
+    name?: string;
+}
+interface FieldVariableArg extends FieldVariableFromJsonConfig {
+    type: 'field_variable';
+    name?: string;
+}
+export {};
+//# sourceMappingURL=i_json_block_definition.d.ts.map

package/core/interfaces/i_keyboard_accessible.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { KeyboardShortcut } from '../shortcut_registry.js';
+import type { KeyboardShortcut } from '../shortcut_registry.js';
 /**
  * An interface for an object that handles keyboard shortcuts.
  */

package/core/interfaces/i_navigation_policy.d.ts

@@ -38,6 +38,18 @@ export interface INavigationPolicy<T> {
      *     there is none.
      */
     getPreviousSibling(current: T): IFocusableNode | null;
+    /**
+     * Returns an ID corresponding to the visual "row" the given element is part
+     * of. All elements on the same visual row should share the same ID. For
+     * example, icons share their parent block's row ID, as do inline connected
+     * blocks or value inputs. Statement inputs, external inputs, or blocks
+     * connected to one another's previous or next connections form distinct
+     * visual rows and should have distinct row IDs.
+     *
+     * @param current The element to return the row ID of.
+     * @returns The row ID of the given element.
+     */
+    getRowId(current: T): string;
     /**
      * Returns whether or not the given instance should be reachable via keyboard
      * navigation.

package/core/interfaces/i_parameter_model.d.ts

@@ -3,8 +3,8 @@
  * Copyright 2022 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { ParameterState } from '../serialization/procedures';
-import { IProcedureModel } from './i_procedure_model';
+import type { ParameterState } from '../serialization/procedures';
+import type { IProcedureModel } from './i_procedure_model';
 /**
  * A data model for a procedure.
  */

package/core/interfaces/i_paster.d.ts

@@ -3,9 +3,9 @@
  * Copyright 2023 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Coordinate } from '../utils/coordinate.js';
-import { WorkspaceSvg } from '../workspace_svg.js';
-import { ICopyable, ICopyData } from './i_copyable.js';
+import type { Coordinate } from '../utils/coordinate.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import type { ICopyable, ICopyData } from './i_copyable.js';
 /** An object that can paste data into a workspace. */
 export interface IPaster<U extends ICopyData, T extends ICopyable<U>> {
     paste(copyData: U, workspace: WorkspaceSvg, coordinate?: Coordinate): T | null;

package/core/interfaces/i_procedure_block.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Block } from '../block.js';
-import { IProcedureModel } from './i_procedure_model.js';
+import type { IProcedureModel } from './i_procedure_model.js';
 /** The interface for a block which models a procedure. */
 export interface IProcedureBlock {
     getProcedureModel(): IProcedureModel;

package/core/interfaces/i_procedure_map.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2022 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { IProcedureModel } from './i_procedure_model.js';
+import type { IProcedureModel } from './i_procedure_model.js';
 export interface IProcedureMap extends Map<string, IProcedureModel> {
     /**
      * Adds the given ProcedureModel to the map of procedure models, so that

package/core/interfaces/i_procedure_model.d.ts

@@ -3,8 +3,8 @@
  * Copyright 2022 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { State } from '../serialization/procedures.js';
-import { IParameterModel } from './i_parameter_model.js';
+import type { State } from '../serialization/procedures.js';
+import type { IParameterModel } from './i_parameter_model.js';
 /**
  * A data model for a procedure.
  */

package/core/interfaces/i_selectable.d.ts

@@ -3,8 +3,8 @@
  * Copyright 2019 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { Workspace } from '../workspace.js';
-import { IFocusableNode } from './i_focusable_node.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import type { IFocusableNode } from './i_focusable_node.js';
 /**
  * The interface for an object that is selectable.
  *
@@ -15,7 +15,7 @@ import { IFocusableNode } from './i_focusable_node.js';
  */
 export interface ISelectable extends IFocusableNode {
     id: string;
-    workspace: Workspace;
+    workspace: WorkspaceSvg;
     /** Select this.  Highlight it visually. */
     select(): void;
     /** Unselect this.  Unhighlight it visually. */

package/core/interfaces/i_selectable_toolbox_item.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { FlyoutItemInfoArray } from '../utils/toolbox';
-import type { IToolboxItem } from './i_toolbox_item.js';
+import { type IToolboxItem } from './i_toolbox_item.js';
 /**
  * Interface for an item in the toolbox that can be selected.
  */
@@ -45,7 +45,7 @@ export interface ISelectableToolboxItem extends IToolboxItem {
     onClick(_e: Event): void;
 }
 /**
- * Type guard that checks whether an IToolboxItem is an ISelectableToolboxItem.
+ * Type guard that checks whether an object is an ISelectableToolboxItem.
  */
-export declare function isSelectableToolboxItem(toolboxItem: IToolboxItem): toolboxItem is ISelectableToolboxItem;
+export declare function isSelectableToolboxItem(obj: any): obj is ISelectableToolboxItem;
 //# sourceMappingURL=i_selectable_toolbox_item.d.ts.map

package/core/interfaces/i_toolbox.d.ts

@@ -98,5 +98,9 @@ export interface IToolbox extends IRegistrable, IFocusableTree {
     setSelectedItem(item: IToolboxItem | null): void;
     /** Disposes of this toolbox. */
     dispose(): void;
+    /**
+     * Returns a list of items in this toolbox.
+     */
+    getToolboxItems(): IToolboxItem[];
 }
 //# sourceMappingURL=i_toolbox.d.ts.map

package/core/interfaces/i_toolbox_item.d.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { IFocusableNode } from './i_focusable_node.js';
+import type { IToolbox } from './i_toolbox.js';
 /**
  * Interface for an item in the toolbox.
  */
@@ -67,5 +68,10 @@ export interface IToolboxItem extends IFocusableNode {
      * @param isVisible True if category should be visible.
      */
     setVisible_(isVisible: boolean): void;
+    getParentToolbox(): IToolbox;
 }
+/**
+ * Type guard that checks whether an object is an IToolboxItem.
+ */
+export declare function isToolboxItem(obj: any): obj is IToolboxItem;
 //# sourceMappingURL=i_toolbox_item.d.ts.map

package/core/interfaces/i_variable_backed_parameter_model.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2023 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { IParameterModel } from './i_parameter_model.js';
+import type { IParameterModel } from './i_parameter_model.js';
 import type { IVariableModel, IVariableState } from './i_variable_model.js';
 /** Interface for a parameter model that holds a variable model. */
 export interface IVariableBackedParameterModel extends IParameterModel {