blockly 12.4.0 → 12.4.1

package/core/theme/zelos.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Theme } from '../theme.js';
+/**
+ * Zelos theme.
+ */
+export declare const Zelos: Theme;
+//# sourceMappingURL=zelos.d.ts.map

package/core/theme.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface ITheme {
+    blockStyles?: {
+        [key: string]: Partial<BlockStyle>;
+    };
+    categoryStyles?: {
+        [key: string]: CategoryStyle;
+    };
+    componentStyles?: ComponentStyle;
+    fontStyle?: FontStyle;
+    startHats?: boolean;
+    base?: string | Theme;
+    name: string;
+}
+/**
+ * Class for a theme.
+ */
+export declare class Theme implements ITheme {
+    name: string;
+    /** @internal */
+    blockStyles: {
+        [key: string]: BlockStyle;
+    };
+    /** @internal */
+    categoryStyles: {
+        [key: string]: CategoryStyle;
+    };
+    /** @internal */
+    componentStyles: ComponentStyle;
+    /** @internal */
+    fontStyle: FontStyle;
+    /**
+     * Whether or not to add a 'hat' on top of all blocks with no previous or
+     * output connections.
+     *
+     * @internal
+     */
+    startHats?: boolean;
+    /**
+     * @param name Theme name.
+     * @param opt_blockStyles A map from style names (strings) to objects with
+     *     style attributes for blocks.
+     * @param opt_categoryStyles A map from style names (strings) to objects with
+     *     style attributes for categories.
+     * @param opt_componentStyles A map of Blockly component names to style value.
+     */
+    constructor(name: string, opt_blockStyles?: {
+        [key: string]: Partial<BlockStyle>;
+    }, opt_categoryStyles?: {
+        [key: string]: CategoryStyle;
+    }, opt_componentStyles?: ComponentStyle);
+    /**
+     * Gets the class name that identifies this theme.
+     *
+     * @returns The CSS class name.
+     * @internal
+     */
+    getClassName(): string;
+    /**
+     * Overrides or adds a style to the blockStyles map.
+     *
+     * @param blockStyleName The name of the block style.
+     * @param blockStyle The block style.
+     */
+    setBlockStyle(blockStyleName: string, blockStyle: BlockStyle): void;
+    /**
+     * Overrides or adds a style to the categoryStyles map.
+     *
+     * @param categoryStyleName The name of the category style.
+     * @param categoryStyle The category style.
+     */
+    setCategoryStyle(categoryStyleName: string, categoryStyle: CategoryStyle): void;
+    /**
+     * Gets the style for a given Blockly UI component.  If the style value is a
+     * string, we attempt to find the value of any named references.
+     *
+     * @param componentName The name of the component.
+     * @returns The style value.
+     */
+    getComponentStyle(componentName: string): string | null;
+    /**
+     * Configure a specific Blockly UI component with a style value.
+     *
+     * @param componentName The name of the component.
+     * @param styleValue The style value.
+     */
+    setComponentStyle(componentName: string, styleValue: any): void;
+    /**
+     * Configure a theme's font style.
+     *
+     * @param fontStyle The font style.
+     */
+    setFontStyle(fontStyle: FontStyle): void;
+    /**
+     * Configure a theme's start hats.
+     *
+     * @param startHats True if the theme enables start hats, false otherwise.
+     */
+    setStartHats(startHats: boolean): void;
+    /**
+     * Define a new Blockly theme.
+     *
+     * @param name The name of the theme.
+     * @param themeObj An object containing theme properties.
+     * @returns A new Blockly theme.
+     */
+    static defineTheme(name: string, themeObj: ITheme): Theme;
+}
+export declare namespace Theme {
+    interface BlockStyle {
+        colourPrimary: string;
+        colourSecondary: string;
+        colourTertiary: string;
+        hat: string;
+    }
+    interface CategoryStyle {
+        colour: string;
+    }
+    interface ComponentStyle {
+        workspaceBackgroundColour?: string;
+        toolboxBackgroundColour?: string;
+        toolboxForegroundColour?: string;
+        flyoutBackgroundColour?: string;
+        flyoutForegroundColour?: string;
+        flyoutOpacity?: number;
+        scrollbarColour?: string;
+        scrollbarOpacity?: number;
+        insertionMarkerColour?: string;
+        insertionMarkerOpacity?: number;
+        markerColour?: string;
+        cursorColour?: string;
+        selectedGlowColour?: string;
+        selectedGlowOpacity?: number;
+        replacementGlowColour?: string;
+        replacementGlowOpacity?: number;
+    }
+    interface FontStyle {
+        family?: string;
+        weight?: string;
+        size?: number;
+    }
+}
+export type BlockStyle = Theme.BlockStyle;
+export type CategoryStyle = Theme.CategoryStyle;
+export type ComponentStyle = Theme.ComponentStyle;
+export type FontStyle = Theme.FontStyle;
+//# sourceMappingURL=theme.d.ts.map

package/core/theme_manager.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Object in charge of storing and updating a workspace theme
+ *     and UI components.
+ *
+ * @class
+ */
+import type { Theme } from './theme.js';
+import type { Workspace } from './workspace.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for storing and updating a workspace's theme and UI components.
+ */
+export declare class ThemeManager {
+    private readonly workspace;
+    private theme;
+    /** A list of workspaces that are subscribed to this theme. */
+    private subscribedWorkspaces;
+    private componentDB;
+    /**
+     * @param workspace The main workspace.
+     * @param theme The workspace theme.
+     * @internal
+     */
+    constructor(workspace: WorkspaceSvg, theme: Theme);
+    /**
+     * Get the workspace theme.
+     *
+     * @returns The workspace theme.
+     * @internal
+     */
+    getTheme(): Theme;
+    /**
+     * Set the workspace theme, and refresh the workspace and all components.
+     *
+     * @param theme The workspace theme.
+     * @internal
+     */
+    setTheme(theme: Theme): void;
+    /**
+     * Subscribe a workspace to changes to the selected theme.  If a new theme is
+     * set, the workspace is called to refresh its blocks.
+     *
+     * @param workspace The workspace to subscribe.
+     * @internal
+     */
+    subscribeWorkspace(workspace: Workspace): void;
+    /**
+     * Unsubscribe a workspace to changes to the selected theme.
+     *
+     * @param workspace The workspace to unsubscribe.
+     * @internal
+     */
+    unsubscribeWorkspace(workspace: Workspace): void;
+    /**
+     * Subscribe an element to changes to the selected theme.  If a new theme is
+     * selected, the element's style is refreshed with the new theme's style.
+     *
+     * @param element The element to subscribe.
+     * @param componentName The name used to identify the component. This must be
+     *     the same name used to configure the style in the Theme object.
+     * @param propertyName The inline style property name to update.
+     * @internal
+     */
+    subscribe(element: HTMLElement | SVGElement, componentName: string, propertyName: string): void;
+    /**
+     * Unsubscribe an element to changes to the selected theme.
+     *
+     * @param element The element to unsubscribe.
+     * @internal
+     */
+    unsubscribe(element: HTMLElement | SVGElement): void;
+    /**
+     * Dispose of this theme manager.
+     *
+     * @internal
+     */
+    dispose(): void;
+}
+export declare namespace ThemeManager {
+    /** The type for a Blockly UI Component. */
+    interface Component {
+        element: HTMLElement | SVGElement;
+        propertyName: string;
+    }
+}
+export type Component = ThemeManager.Component;
+//# sourceMappingURL=theme_manager.d.ts.map

package/core/toast.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Display/configuration options for a toast notification.
+ */
+export interface ToastOptions {
+    /**
+     * Toast ID. If set along with `oncePerSession`, will cause subsequent toasts
+     * with this ID to not be shown.
+     */
+    id?: string;
+    /**
+     * Flag to show the toast once per session only.
+     * Subsequent calls are ignored.
+     */
+    oncePerSession?: boolean;
+    /**
+     * Text of the message to display on the toast.
+     */
+    message: string;
+    /**
+     * Duration in seconds before the toast is removed. Defaults to 5.
+     */
+    duration?: number;
+    /**
+     * How prominently/interrupting the readout of the toast should be for
+     * screenreaders. Corresponds to aria-live and defaults to polite.
+     */
+    assertiveness?: Toast.Assertiveness;
+}
+/**
+ * Class that allows for showing and dismissing temporary notifications.
+ */
+export declare class Toast {
+    /** IDs of toasts that have previously been shown. */
+    private static shownIds;
+    /**
+     * Shows a toast notification.
+     *
+     * @param workspace The workspace to show the toast on.
+     * @param options Configuration options for the toast message, duration, etc.
+     */
+    static show(workspace: WorkspaceSvg, options: ToastOptions): void;
+    /**
+     * Creates the DOM representation of a toast.
+     *
+     * @param workspace The workspace to inject the toast notification onto.
+     * @param options Configuration options for the toast.
+     * @returns The root DOM element of the toast.
+     */
+    protected static createDom(workspace: WorkspaceSvg, options: ToastOptions): HTMLDivElement;
+    /**
+     * Dismiss a toast, e.g. in response to a user action.
+     *
+     * @param workspace The workspace to dismiss a toast in.
+     * @param id The toast ID, or undefined to clear any toast.
+     */
+    static hide(workspace: WorkspaceSvg, id?: string): void;
+}
+/**
+ * Options for how aggressively toasts should be read out by screenreaders.
+ * Values correspond to those for aria-live.
+ */
+export declare namespace Toast {
+    enum Assertiveness {
+        ASSERTIVE = "assertive",
+        POLITE = "polite"
+    }
+}
+//# sourceMappingURL=toast.d.ts.map

package/core/toolbox/category.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ICollapsibleToolboxItem } from '../interfaces/i_collapsible_toolbox_item.js';
+import type { ISelectableToolboxItem } from '../interfaces/i_selectable_toolbox_item.js';
+import type { IToolbox } from '../interfaces/i_toolbox.js';
+import type { CategoryInfo, FlyoutDefinition, FlyoutItemInfoArray } from '../utils/toolbox.js';
+import { ToolboxItem } from './toolbox_item.js';
+/**
+ * Class for a category in a toolbox.
+ */
+export declare class ToolboxCategory extends ToolboxItem implements ISelectableToolboxItem {
+    /** Name used for registering a toolbox category. */
+    static registrationName: string;
+    /** The number of pixels to move the category over at each nested level. */
+    static nestedPadding: number;
+    /** The width in pixels of the strip of colour next to each category. */
+    static borderWidth: number;
+    /**
+     * The default colour of the category. This is used as the background colour
+     * of the category when it is selected.
+     */
+    static defaultBackgroundColour: string;
+    toolboxItemDef_: CategoryInfo;
+    /** The name that will be displayed on the category. */
+    protected name_: string;
+    /** The colour of the category. */
+    protected colour_: string;
+    /** The HTML container for the category. */
+    protected htmlDiv_: HTMLDivElement | null;
+    /** The HTML element for the category row. */
+    protected rowDiv_: HTMLDivElement | null;
+    /** The HTML element that holds children elements of the category row. */
+    protected rowContents_: HTMLDivElement | null;
+    /** The HTML element for the toolbox icon. */
+    protected iconDom_: Element | null;
+    /** The HTML element for the toolbox label. */
+    protected labelDom_: Element | null;
+    protected cssConfig_: CssConfig;
+    /** True if the category is meant to be hidden, false otherwise. */
+    protected isHidden_: boolean;
+    /** True if this category is disabled, false otherwise. */
+    protected isDisabled_: boolean;
+    /** The flyout items for this category. */
+    protected flyoutItems_: string | FlyoutItemInfoArray;
+    /**
+     * @param categoryDef The information needed to create a category in the
+     *     toolbox.
+     * @param parentToolbox The parent toolbox for the category.
+     * @param opt_parent The parent category or null if the category does not have
+     *     a parent.
+     */
+    constructor(categoryDef: CategoryInfo, parentToolbox: IToolbox, opt_parent?: ICollapsibleToolboxItem);
+    /**
+     * Initializes the toolbox item.
+     * This includes creating the DOM and updating the state of any items based
+     * on the info object.
+     * Init should be called immediately after the construction of the toolbox
+     * item, to ensure that the category contents are properly parsed.
+     */
+    init(): void;
+    /**
+     * Creates an object holding the default classes for a category.
+     *
+     * @returns The configuration object holding all the CSS classes for a
+     *     category.
+     */
+    protected makeDefaultCssConfig_(): CssConfig;
+    /**
+     * Parses the contents array depending on if the category is a dynamic
+     * category, or if its contents are meant to be shown in the flyout.
+     *
+     * @param categoryDef The information needed to create a category.
+     */
+    protected parseContents_(categoryDef: CategoryInfo): void;
+    /**
+     * Parses the non-contents parts of the category def.
+     *
+     * @param categoryDef The information needed to create a category.
+     */
+    protected parseCategoryDef_(categoryDef: CategoryInfo): void;
+    /**
+     * Creates the DOM for the category.
+     *
+     * @returns The parent element for the category.
+     */
+    protected createDom_(): HTMLDivElement;
+    /**
+     * Creates the container that holds the row and any subcategories.
+     *
+     * @returns The div that holds the icon and the label.
+     */
+    protected createContainer_(): HTMLDivElement;
+    /**
+     * Creates the parent of the contents container. All clicks will happen on
+     * this div.
+     *
+     * @returns The div that holds the contents container.
+     */
+    protected createRowContainer_(): HTMLDivElement;
+    /**
+     * Creates the container for the label and icon.
+     * This is necessary so we can set all subcategory pointer events to none.
+     *
+     * @returns The div that holds the icon and the label.
+     */
+    protected createRowContentsContainer_(): HTMLDivElement;
+    /**
+     * Creates the span that holds the category icon.
+     *
+     * @returns The span that holds the category icon.
+     */
+    protected createIconDom_(): Element;
+    /**
+     * Creates the span that holds the category label.
+     * This should have an ID for accessibility purposes.
+     *
+     * @param name The name of the category.
+     * @returns The span that holds the category label.
+     */
+    protected createLabelDom_(name: string): Element;
+    /** Updates the colour for this category. */
+    refreshTheme(): void;
+    /**
+     * Add the strip of colour to the toolbox category.
+     *
+     * @param colour The category colour.
+     */
+    protected addColourBorder_(colour: string): void;
+    /**
+     * Gets either the colour or the style for a category.
+     *
+     * @param categoryDef The object holding information on the category.
+     * @returns The hex colour for the category.
+     */
+    protected getColour_(categoryDef: CategoryInfo): string;
+    /**
+     * Sets the colour for the category using the style name and returns the new
+     * colour as a hex string.
+     *
+     * @param styleName Name of the style.
+     * @returns The hex colour for the category.
+     */
+    private getColourfromStyle;
+    /**
+     * Gets the HTML element that is clickable.
+     * The parent toolbox element receives clicks. The parent toolbox will add an
+     * ID to this element so it can pass the onClick event to the correct
+     * toolboxItem.
+     *
+     * @returns The HTML element that receives clicks.
+     */
+    getClickTarget(): Element;
+    /**
+     * Parses the colour on the category.
+     *
+     * @param colourValue HSV hue value (0 to 360), #RRGGBB string, or a message
+     *     reference string pointing to one of those two values.
+     * @returns The hex colour for the category.
+     */
+    private parseColour;
+    /**
+     * Adds appropriate classes to display an open icon.
+     *
+     * @param iconDiv The div that holds the icon.
+     */
+    protected openIcon_(iconDiv: Element | null): void;
+    /**
+     * Adds appropriate classes to display a closed icon.
+     *
+     * @param iconDiv The div that holds the icon.
+     */
+    protected closeIcon_(iconDiv: Element | null): void;
+    /**
+     * Sets whether the category is visible or not.
+     * For a category to be visible its parent category must also be expanded.
+     *
+     * @param isVisible True if category should be visible.
+     */
+    setVisible_(isVisible: boolean): void;
+    /** Hide the category. */
+    hide(): void;
+    /**
+     * Show the category. Category will only appear if its parent category is also
+     * expanded.
+     */
+    show(): void;
+    /**
+     * Whether the category is visible.
+     * A category is only visible if all of its ancestors are expanded and
+     * isHidden_ is false.
+     *
+     * @returns True if the category is visible, false otherwise.
+     */
+    isVisible(): boolean;
+    /**
+     * Whether all ancestors of a category (parent and parent's parent, etc.) are
+     * expanded.
+     *
+     * @returns True only if every ancestor is expanded
+     */
+    protected allAncestorsExpanded_(): boolean;
+    isSelectable(): boolean;
+    /**
+     * Handles when the toolbox item is clicked.
+     *
+     * @param _e Click event to handle.
+     */
+    onClick(_e: Event): void;
+    /**
+     * Sets the current category as selected.
+     *
+     * @param isSelected True if this category is selected, false otherwise.
+     */
+    setSelected(isSelected: boolean): void;
+    /**
+     * Sets whether the category is disabled.
+     *
+     * @param isDisabled True to disable the category, false otherwise.
+     */
+    setDisabled(isDisabled: boolean): void;
+    /**
+     * Gets the name of the category. Used for emitting events.
+     *
+     * @returns The name of the toolbox item.
+     */
+    getName(): string;
+    getParent(): ICollapsibleToolboxItem | null;
+    getDiv(): HTMLDivElement | null;
+    /**
+     * Gets the contents of the category. These are items that are meant to be
+     * displayed in the flyout.
+     *
+     * @returns The definition of items to be displayed in the flyout.
+     */
+    getContents(): FlyoutItemInfoArray | string;
+    /**
+     * Updates the contents to be displayed in the flyout.
+     * If the flyout is open when the contents are updated, refreshSelection on
+     * the toolbox must also be called.
+     *
+     * @param contents The contents to be displayed in the flyout. A string can be
+     *     supplied to create a dynamic category.
+     */
+    updateFlyoutContents(contents: FlyoutDefinition | string): void;
+    dispose(): void;
+}
+export declare namespace ToolboxCategory {
+    /** All the CSS class names that are used to create a category. */
+    interface CssConfig {
+        container?: string;
+        row?: string;
+        rowcontentcontainer?: string;
+        icon?: string;
+        label?: string;
+        contents?: string;
+        selected?: string;
+        openicon?: string;
+        closedicon?: string;
+    }
+}
+export type CssConfig = ToolboxCategory.CssConfig;
+//# sourceMappingURL=category.d.ts.map

package/core/toolbox/collapsible_category.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A toolbox category used to organize blocks in the toolbox.
+ *
+ * @class
+ */
+import type { ICollapsibleToolboxItem } from '../interfaces/i_collapsible_toolbox_item.js';
+import type { IToolbox } from '../interfaces/i_toolbox.js';
+import type { IToolboxItem } from '../interfaces/i_toolbox_item.js';
+import * as toolbox from '../utils/toolbox.js';
+import { ToolboxCategory } from './category.js';
+/**
+ * Class for a category in a toolbox that can be collapsed.
+ */
+export declare class CollapsibleToolboxCategory extends ToolboxCategory implements ICollapsibleToolboxItem {
+    /** Name used for registering a collapsible toolbox category. */
+    static registrationName: string;
+    /** Container for any child categories. */
+    protected subcategoriesDiv_: HTMLDivElement | null;
+    /** Whether or not the category should display its subcategories. */
+    protected expanded_: boolean;
+    /** The child toolbox items for this category. */
+    protected toolboxItems_: IToolboxItem[];
+    /**
+     * @param categoryDef The information needed to create a category in the
+     *     toolbox.
+     * @param toolbox The parent toolbox for the category.
+     * @param opt_parent The parent category or null if the category does not have
+     *     a parent.
+     */
+    constructor(categoryDef: toolbox.CategoryInfo, toolbox: IToolbox, opt_parent?: ICollapsibleToolboxItem);
+    makeDefaultCssConfig_(): ToolboxCategory.CssConfig;
+    parseContents_(categoryDef: toolbox.CategoryInfo): void;
+    /**
+     * Creates a toolbox item and adds it to the list of toolbox items.
+     *
+     * @param itemDef The information needed to create a toolbox item.
+     */
+    private createToolboxItem;
+    init(): void;
+    createDom_(): HTMLDivElement;
+    createIconDom_(): HTMLSpanElement;
+    /**
+     * Create the DOM for all subcategories.
+     *
+     * @param subcategories The subcategories.
+     * @returns The div holding all the subcategories.
+     */
+    protected createSubCategoriesDom_(subcategories: IToolboxItem[]): HTMLDivElement;
+    /**
+     * Opens or closes the current category and the associated flyout.
+     *
+     * @param isExpanded True to expand the category, false to close.
+     */
+    setExpanded(isExpanded: boolean): void;
+    setVisible_(isVisible: boolean): void;
+    /**
+     * Whether the category is expanded to show its child subcategories.
+     *
+     * @returns True if the toolbox item shows its children, false if it is
+     *     collapsed.
+     */
+    isExpanded(): boolean;
+    isCollapsible(): boolean;
+    onClick(_e: Event): void;
+    /** Toggles whether or not the category is expanded. */
+    toggleExpanded(): void;
+    getDiv(): HTMLDivElement | null;
+    /**
+     * Gets any children toolbox items. (ex. Gets the subcategories)
+     *
+     * @returns The child toolbox items.
+     */
+    getChildToolboxItems(): IToolboxItem[];
+}
+export declare namespace CollapsibleToolboxCategory {
+    /**
+     * All the CSS class names that are used to create a collapsible
+     * category. This is all the properties from the regular category plus
+     * contents.
+     */
+    interface CssConfig {
+        container: string | null;
+        row: string | null;
+        rowcontentcontainer: string | null;
+        icon: string | null;
+        label: string | null;
+        selected: string | null;
+        openicon: string | null;
+        closedicon: string | null;
+        contents: string | null;
+    }
+}
+export type CssConfig = CollapsibleToolboxCategory.CssConfig;
+//# sourceMappingURL=collapsible_category.d.ts.map