blockly 8.0.5 → 9.0.0-beta.0

package/core/theme.ts

@@ -0,0 +1,221 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The class representing a theme.
+ */
+
+/**
+ * The class representing a theme.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Theme');
+
+import * as registry from './registry.js';
+import * as object from './utils/object.js';
+
+
+export interface ITheme {
+  blockStyles: {[key: string]: BlockStyle};
+  categoryStyles: {[key: string]: CategoryStyle};
+  componentStyles: ComponentStyle;
+  fontStyle: FontStyle;
+  startHats: boolean|null;
+  base?: string|Theme;
+  name: string;
+}
+
+/**
+ * Class for a theme.
+ * @alias Blockly.Theme
+ */
+export class Theme implements ITheme {
+  /** @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|null = null;
+
+  /**
+   * @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(
+      public name: string, opt_blockStyles?: {[key: string]: BlockStyle},
+      opt_categoryStyles?: {[key: string]: CategoryStyle},
+      opt_componentStyles?: ComponentStyle) {
+    /** The block styles map. */
+    this.blockStyles = opt_blockStyles || Object.create(null);
+
+    /** The category styles map. */
+    this.categoryStyles = opt_categoryStyles || Object.create(null);
+
+    /** The UI components styles map. */
+    this.componentStyles =
+        opt_componentStyles || Object.create(null) as ComponentStyle;
+
+    /** The font style. */
+    this.fontStyle = Object.create(null) as FontStyle;
+
+    // Register the theme by name.
+    registry.register(registry.Type.THEME, name, this);
+  }
+
+  /**
+   * Gets the class name that identifies this theme.
+   * @return The CSS class name.
+   * @internal
+   */
+  getClassName(): string {
+    return this.name + '-theme';
+  }
+
+  /**
+   * 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) {
+    this.blockStyles[blockStyleName] = blockStyle;
+  }
+
+  /**
+   * 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) {
+    this.categoryStyles[categoryStyleName] = categoryStyle;
+  }
+
+  /**
+   * 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.
+   * @return The style value.
+   */
+  getComponentStyle(componentName: string): string|null {
+    const style = (this.componentStyles as AnyDuringMigration)[componentName];
+    if (style && typeof style === 'string' && this.getComponentStyle((style))) {
+      return this.getComponentStyle((style));
+    }
+    return style ? String(style) : 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: AnyDuringMigration) {
+    (this.componentStyles as AnyDuringMigration)[componentName] = styleValue;
+  }
+
+  /**
+   * Configure a theme's font style.
+   * @param fontStyle The font style.
+   */
+  setFontStyle(fontStyle: FontStyle) {
+    this.fontStyle = fontStyle;
+  }
+
+  /**
+   * Configure a theme's start hats.
+   * @param startHats True if the theme enables start hats, false otherwise.
+   */
+  setStartHats(startHats: boolean) {
+    this.startHats = startHats;
+  }
+
+  /**
+   * Define a new Blockly theme.
+   * @param name The name of the theme.
+   * @param themeObj An object containing theme properties.
+   * @return A new Blockly theme.
+   */
+  static defineTheme(name: string, themeObj: ITheme): Theme {
+    name = name.toLowerCase();
+    const theme = new Theme(name);
+    let base = themeObj['base'];
+    if (base) {
+      if (typeof base === 'string') {
+        base = registry.getObject(registry.Type.THEME, base) ?? undefined;
+      }
+      if (base instanceof Theme) {
+        object.deepMerge(theme, base);
+        theme.name = name;
+      }
+    }
+
+    object.deepMerge(theme.blockStyles, themeObj['blockStyles']);
+    object.deepMerge(theme.categoryStyles, themeObj['categoryStyles']);
+    object.deepMerge(theme.componentStyles, themeObj['componentStyles']);
+    object.deepMerge(theme.fontStyle, themeObj['fontStyle']);
+    if (themeObj['startHats'] !== null) {
+      theme.startHats = themeObj['startHats'];
+    }
+
+    return theme;
+  }
+}
+
+export namespace Theme {
+  export interface BlockStyle {
+    colourPrimary: string;
+    colourSecondary: string;
+    colourTertiary: string;
+    hat?: string;
+  }
+
+  export interface CategoryStyle {
+    colour: string;
+  }
+
+  export interface ComponentStyle {
+    workspaceBackgroundColour: string|null;
+    toolboxBackgroundColour: string|null;
+    toolboxForegroundColour: string|null;
+    flyoutBackgroundColour: string|null;
+    flyoutForegroundColour: string|null;
+    flyoutOpacity: number|null;
+    scrollbarColour: string|null;
+    scrollbarOpacity: number|null;
+    insertionMarkerColour: string|null;
+    insertionMarkerOpacity: number|null;
+    markerColour: string|null;
+    cursorColour: string|null;
+    selectedGlowColour: string|null;
+    selectedGlowOpacity: number|null;
+    replacementGlowColour: string|null;
+    replacementGlowOpacity: number|null;
+  }
+
+  export interface FontStyle {
+    family: string|null;
+    weight: string|null;
+    size: number|null;
+  }
+}
+
+export type BlockStyle = Theme.BlockStyle;
+export type CategoryStyle = Theme.CategoryStyle;
+export type ComponentStyle = Theme.ComponentStyle;
+export type FontStyle = Theme.FontStyle;

package/core/theme_manager.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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.
+ * @alias Blockly.ThemeManager
+ */
+export declare class ThemeManager {
+    private readonly workspace;
+    private theme;
+    /** A list of workspaces that are subscribed to this theme. */
+    private subscribedWorkspaces_;
+    private componentDB;
+    owner_: any;
+    /**
+     * @param workspace The main workspace.
+     * @param theme The workspace theme.
+     * @internal
+     */
+    constructor(workspace: WorkspaceSvg, theme: Theme);
+    /**
+     * Get the workspace theme.
+     * @return 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: Element, componentName: string, propertyName: string): void;
+    /**
+     * Unsubscribe an element to changes to the selected theme.
+     * @param element The element to unsubscribe.
+     * @internal
+     */
+    unsubscribe(element: Element): void;
+    /**
+     * Dispose of this theme manager.
+     * @suppress {checkTypes}
+     * @internal
+     */
+    dispose(): void;
+}
+export declare namespace ThemeManager {
+    /** The type for a Blockly UI Component. */
+    interface Component {
+        element: Element;
+        propertyName: string;
+    }
+}
+export declare type Component = ThemeManager.Component;

package/core/theme_manager.ts

@@ -0,0 +1,186 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Object in charge of storing and updating a workspace theme
+ *     and UI components.
+ */
+
+/**
+ * Object in charge of storing and updating a workspace theme
+ *     and UI components.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.ThemeManager');
+
+import type {Theme} from './theme.js';
+import * as arrayUtils from './utils/array.js';
+import * as dom from './utils/dom.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.
+ * @alias Blockly.ThemeManager
+ */
+export class ThemeManager {
+  /** A list of workspaces that are subscribed to this theme. */
+  private subscribedWorkspaces_: Workspace[] = [];
+  private componentDB = new Map<string, Component[]>();
+  owner_: AnyDuringMigration;
+
+  /**
+   * @param workspace The main workspace.
+   * @param theme The workspace theme.
+   * @internal
+   */
+  constructor(private readonly workspace: WorkspaceSvg, private theme: Theme) {}
+
+  /**
+   * Get the workspace theme.
+   * @return The workspace theme.
+   * @internal
+   */
+  getTheme(): Theme {
+    return this.theme;
+  }
+
+  /**
+   * Set the workspace theme, and refresh the workspace and all components.
+   * @param theme The workspace theme.
+   * @internal
+   */
+  setTheme(theme: Theme) {
+    const prevTheme = this.theme;
+    this.theme = theme;
+    // Set the theme name onto the injection div.
+    const injectionDiv = this.workspace.getInjectionDiv();
+    if (injectionDiv) {
+      if (prevTheme) {
+        dom.removeClass(injectionDiv, prevTheme.getClassName());
+      }
+      dom.addClass(injectionDiv, this.theme.getClassName());
+    }
+
+    // Refresh all subscribed workspaces.
+    for (let i = 0, workspace; workspace = this.subscribedWorkspaces_[i]; i++) {
+      (workspace as WorkspaceSvg).refreshTheme();
+    }
+
+    // Refresh all registered Blockly UI components.
+    for (const [key, componentList] of this.componentDB) {
+      for (const component of componentList) {
+        const element = component.element;
+        const propertyName = component.propertyName;
+        const style = this.theme && this.theme.getComponentStyle(key);
+        // AnyDuringMigration because:  Property 'style' does not exist on type
+        // 'Element'.
+        (element as AnyDuringMigration).style[propertyName] = style || '';
+      }
+    }
+
+    for (const workspace of this.subscribedWorkspaces_) {
+      (workspace as WorkspaceSvg).hideChaff();
+    }
+  }
+
+  /**
+   * 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) {
+    this.subscribedWorkspaces_.push(workspace);
+  }
+
+  /**
+   * Unsubscribe a workspace to changes to the selected theme.
+   * @param workspace The workspace to unsubscribe.
+   * @internal
+   */
+  unsubscribeWorkspace(workspace: Workspace) {
+    if (!arrayUtils.removeElem(this.subscribedWorkspaces_, workspace)) {
+      throw Error(
+          'Cannot unsubscribe a workspace that hasn\'t been subscribed.');
+    }
+  }
+
+  /**
+   * 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: Element, componentName: string, propertyName: string) {
+    if (!this.componentDB.has(componentName)) {
+      this.componentDB.set(componentName, []);
+    }
+
+    // Add the element to our component map.
+    this.componentDB.get(componentName)!.push({element, propertyName});
+
+    // Initialize the element with its corresponding theme style.
+    const style = this.theme && this.theme.getComponentStyle(componentName);
+    // AnyDuringMigration because:  Property 'style' does not exist on type
+    // 'Element'.
+    (element as AnyDuringMigration).style[propertyName] = style || '';
+  }
+
+  /**
+   * Unsubscribe an element to changes to the selected theme.
+   * @param element The element to unsubscribe.
+   * @internal
+   */
+  unsubscribe(element: Element) {
+    if (!element) {
+      return;
+    }
+    // Go through all component, and remove any references to this element.
+    for (const [componentName, elements] of this.componentDB) {
+      for (let i = elements.length - 1; i >= 0; i--) {
+        if (elements[i].element === element) {
+          elements.splice(i, 1);
+        }
+      }
+      // Clean up the component map entry if the list is empty.
+      if (!elements.length) {
+        this.componentDB.delete(componentName);
+      }
+    }
+  }
+
+  /**
+   * Dispose of this theme manager.
+   * @suppress {checkTypes}
+   * @internal
+   */
+  dispose() {
+    this.owner_ = null;
+    // AnyDuringMigration because:  Type 'null' is not assignable to type
+    // 'Theme'.
+    this.theme = null as AnyDuringMigration;
+    // AnyDuringMigration because:  Type 'null' is not assignable to type
+    // 'Workspace[]'.
+    this.subscribedWorkspaces_ = null as AnyDuringMigration;
+    this.componentDB.clear();
+  }
+}
+
+export namespace ThemeManager {
+  /** The type for a Blockly UI Component. */
+  export interface Component {
+    element: Element;
+    propertyName: string;
+  }
+}
+
+export type Component = ThemeManager.Component;