feat: Add support for displaying toast-style notifications. (#8896)

* feat: Allow resetting alert/prompt/confirm to defaults.

* chore: Add unit tests for Blockly.dialog.

* fix: Removed TEST_ONLY hack from Blockly.dialog.

* feat: Add a default toast notification implementation.

* feat: Add support for toasts to Blockly.dialog.

* chore: Add tests for default toast implementation.

* chore: Fix docstring.

* refactor: Use default arguments for dialog functions.

* refactor: Add 'close' to the list of messages.

* chore: Add new message in several other places.

* chore: clarify docstrings.

* feat: Make toast assertiveness configurable.

Author: gonfunko

core/blockly.ts

@@ -432,6 +432,8 @@ Names.prototype.populateProcedures = function (
 };
 // clang-format on
 
+export * from './toast.js';
+
 // Re-export submodules that no longer declareLegacyNamespace.
 export {
   ASTNode,

core/dialog.ts

@@ -6,31 +6,41 @@
 
 // Former goog.module ID: Blockly.dialog
 
-let alertImplementation = function (
-  message: string,
-  opt_callback?: () => void,
-) {
+import type {ToastOptions} from './toast.js';
+import {Toast} from './toast.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+const defaultAlert = function (message: string, opt_callback?: () => void) {
   window.alert(message);
   if (opt_callback) {
     opt_callback();
   }
 };
 
-let confirmImplementation = function (
+let alertImplementation = defaultAlert;
+
+const defaultConfirm = function (
   message: string,
   callback: (result: boolean) => void,
 ) {
   callback(window.confirm(message));
 };
 
-let promptImplementation = function (
+let confirmImplementation = defaultConfirm;
+
+const defaultPrompt = function (
   message: string,
   defaultValue: string,
   callback: (result: string | null) => void,
 ) {
   callback(window.prompt(message, defaultValue));
 };
 
+let promptImplementation = defaultPrompt;
+
+const defaultToast = Toast.show.bind(Toast);
+let toastImplementation = defaultToast;
+
 /**
  * Wrapper to window.alert() that app developers may override via setAlert to
  * provide alternatives to the modal browser window.
@@ -45,10 +55,16 @@ export function alert(message: string, opt_callback?: () => void) {
 /**
  * Sets the function to be run when Blockly.dialog.alert() is called.
  *
- * @param alertFunction The function to be run.
+ * @param alertFunction The function to be run, or undefined to restore the
+ *     default implementation.
  * @see Blockly.dialog.alert
  */
-export function setAlert(alertFunction: (p1: string, p2?: () => void) => void) {
+export function setAlert(
+  alertFunction: (
+    message: string,
+    callback?: () => void,
+  ) => void = defaultAlert,
+) {
   alertImplementation = alertFunction;
 }
 
@@ -59,25 +75,22 @@ export function setAlert(alertFunction: (p1: string, p2?: () => void) => void) {
  * @param message The message to display to the user.
  * @param callback The callback for handling user response.
  */
-export function confirm(message: string, callback: (p1: boolean) => void) {
-  TEST_ONLY.confirmInternal(message, callback);
-}
-
-/**
- * Private version of confirm for stubbing in tests.
- */
-function confirmInternal(message: string, callback: (p1: boolean) => void) {
+export function confirm(message: string, callback: (result: boolean) => void) {
   confirmImplementation(message, callback);
 }
 
 /**
  * Sets the function to be run when Blockly.dialog.confirm() is called.
  *
- * @param confirmFunction The function to be run.
+ * @param confirmFunction The function to be run, or undefined to restore the
+ *     default implementation.
  * @see Blockly.dialog.confirm
  */
 export function setConfirm(
-  confirmFunction: (p1: string, p2: (p1: boolean) => void) => void,
+  confirmFunction: (
+    message: string,
+    callback: (result: boolean) => void,
+  ) => void = defaultConfirm,
 ) {
   confirmImplementation = confirmFunction;
 }
@@ -95,27 +108,53 @@ export function setConfirm(
 export function prompt(
   message: string,
   defaultValue: string,
-  callback: (p1: string | null) => void,
+  callback: (result: string | null) => void,
 ) {
   promptImplementation(message, defaultValue, callback);
 }
 
 /**
  * Sets the function to be run when Blockly.dialog.prompt() is called.
  *
- * @param promptFunction The function to be run.
+ * @param promptFunction The function to be run, or undefined to restore the
+ *     default implementation.
  * @see Blockly.dialog.prompt
  */
 export function setPrompt(
   promptFunction: (
-    p1: string,
-    p2: string,
-    p3: (p1: string | null) => void,
-  ) => void,
+    message: string,
+    defaultValue: string,
+    callback: (result: string | null) => void,
+  ) => void = defaultPrompt,
 ) {
   promptImplementation = promptFunction;
 }
 
-export const TEST_ONLY = {
-  confirmInternal,
-};
+/**
+ * Displays a temporary notification atop the workspace. Blockly provides a
+ * default toast implementation, but developers may provide their own via
+ * setToast. For simple appearance customization, CSS should be sufficient.
+ *
+ * @param workspace The workspace to display the toast notification atop.
+ * @param options Configuration options for the notification, including its
+ *     message and duration.
+ */
+export function toast(workspace: WorkspaceSvg, options: ToastOptions) {
+  toastImplementation(workspace, options);
+}
+
+/**
+ * Sets the function to be run when Blockly.dialog.toast() is called.
+ *
+ * @param toastFunction The function to be run, or undefined to restore the
+ *     default implementation.
+ * @see Blockly.dialog.toast
+ */
+export function setToast(
+  toastFunction: (
+    workspace: WorkspaceSvg,
+    options: ToastOptions,
+  ) => void = defaultToast,
+) {
+  toastImplementation = toastFunction;
+}

core/toast.ts

@@ -0,0 +1,219 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Css from './css.js';
+import {Msg} from './msg.js';
+import * as aria from './utils/aria.js';
+import * as dom from './utils/dom.js';
+import {Svg} from './utils/svg.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+const CLASS_NAME = 'blocklyToast';
+const MESSAGE_CLASS_NAME = 'blocklyToastMessage';
+const CLOSE_BUTTON_CLASS_NAME = 'blocklyToastCloseButton';
+
+/**
+ * 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 class Toast {
+  /** IDs of toasts that have previously been shown. */
+  private static shownIds = new Set<string>();
+
+  /**
+   * 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) {
+    if (options.oncePerSession && options.id) {
+      if (this.shownIds.has(options.id)) return;
+      this.shownIds.add(options.id);
+    }
+
+    // Clear any existing toasts.
+    this.hide(workspace);
+
+    const toast = this.createDom(workspace, options);
+
+    // Animate the toast into view.
+    requestAnimationFrame(() => {
+      toast.style.bottom = '2rem';
+    });
+  }
+
+  /**
+   * 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) {
+    const {
+      message,
+      duration = 5,
+      assertiveness = Toast.Assertiveness.POLITE,
+    } = options;
+
+    const toast = document.createElement('div');
+    workspace.getInjectionDiv().appendChild(toast);
+    toast.dataset.toastId = options.id;
+    toast.className = CLASS_NAME;
+    aria.setRole(toast, aria.Role.STATUS);
+    aria.setState(toast, aria.State.LIVE, assertiveness);
+
+    const messageElement = toast.appendChild(document.createElement('div'));
+    messageElement.className = MESSAGE_CLASS_NAME;
+    messageElement.innerText = message;
+    const closeButton = toast.appendChild(document.createElement('button'));
+    closeButton.className = CLOSE_BUTTON_CLASS_NAME;
+    aria.setState(closeButton, aria.State.LABEL, Msg['CLOSE']);
+    const closeIcon = dom.createSvgElement(
+      Svg.SVG,
+      {
+        width: 24,
+        height: 24,
+        viewBox: '0 0 24 24',
+        fill: 'none',
+      },
+      closeButton,
+    );
+    aria.setState(closeIcon, aria.State.HIDDEN, true);
+    dom.createSvgElement(
+      Svg.RECT,
+      {
+        x: 19.7782,
+        y: 2.80762,
+        width: 2,
+        height: 24,
+        transform: 'rotate(45, 19.7782, 2.80762)',
+        fill: 'black',
+      },
+      closeIcon,
+    );
+    dom.createSvgElement(
+      Svg.RECT,
+      {
+        x: 2.80762,
+        y: 4.22183,
+        width: 2,
+        height: 24,
+        transform: 'rotate(-45, 2.80762, 4.22183)',
+        fill: 'black',
+      },
+      closeIcon,
+    );
+    closeButton.addEventListener('click', () => {
+      toast.remove();
+      workspace.markFocused();
+    });
+
+    let timeout: ReturnType<typeof setTimeout>;
+    const setToastTimeout = () => {
+      timeout = setTimeout(() => toast.remove(), duration * 1000);
+    };
+    const clearToastTimeout = () => clearTimeout(timeout);
+    toast.addEventListener('focusin', clearToastTimeout);
+    toast.addEventListener('focusout', setToastTimeout);
+    toast.addEventListener('mouseenter', clearToastTimeout);
+    toast.addEventListener('mousemove', clearToastTimeout);
+    toast.addEventListener('mouseleave', setToastTimeout);
+    setToastTimeout();
+
+    return toast;
+  }
+
+  /**
+   * 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) {
+    const toast = workspace.getInjectionDiv().querySelector(`.${CLASS_NAME}`);
+    if (toast instanceof HTMLElement && (!id || id === toast.dataset.toastId)) {
+      toast.remove();
+    }
+  }
+}
+
+/**
+ * Options for how aggressively toasts should be read out by screenreaders.
+ * Values correspond to those for aria-live.
+ */
+export namespace Toast {
+  export enum Assertiveness {
+    ASSERTIVE = 'assertive',
+    POLITE = 'polite',
+  }
+}
+
+Css.register(`
+.${CLASS_NAME} {
+  font-size: 1.2rem;
+  position: absolute;
+  bottom: -10rem;
+  right: 2rem;
+  padding: 1rem;
+  color: black;
+  background-color: white;
+  border: 2px solid black;
+  border-radius: 0.4rem;
+  z-index: 999;
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  line-height: 1.5;
+  transition: bottom 0.3s ease-out;
+}
+
+.${CLASS_NAME} .${MESSAGE_CLASS_NAME} {
+  maxWidth: 18rem;
+}
+
+.${CLASS_NAME} .${CLOSE_BUTTON_CLASS_NAME} {
+  margin: 0;
+  padding: 0.2rem;
+  background-color: transparent;
+  color: black;
+  border: none;
+  cursor: pointer;
+}
+`);