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.

tests/mocha/contextmenu_items_test.js

@@ -318,9 +318,7 @@ suite('Context Menu Items', function () {
 
       test('Deletes all blocks after confirming', function () {
         // Mocks the confirmation dialog and calls the callback with 'true' simulating ok.
-        const confirmStub = sinon
-          .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-          .callsArgWith(1, true);
+        const confirmStub = sinon.stub(window, 'confirm').returns(true);
 
         this.workspace.newBlock('text');
         this.workspace.newBlock('text');
@@ -328,13 +326,13 @@ suite('Context Menu Items', function () {
         this.clock.runAll();
         sinon.assert.calledOnce(confirmStub);
         assert.equal(this.workspace.getTopBlocks(false).length, 0);
+
+        confirmStub.restore();
       });
 
       test('Does not delete blocks if not confirmed', function () {
         // Mocks the confirmation dialog and calls the callback with 'false' simulating cancel.
-        const confirmStub = sinon
-          .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-          .callsArgWith(1, false);
+        const confirmStub = sinon.stub(window, 'confirm').returns(false);
 
         this.workspace.newBlock('text');
         this.workspace.newBlock('text');
@@ -342,19 +340,20 @@ suite('Context Menu Items', function () {
         this.clock.runAll();
         sinon.assert.calledOnce(confirmStub);
         assert.equal(this.workspace.getTopBlocks(false).length, 2);
+
+        confirmStub.restore();
       });
 
       test('No dialog for single block', function () {
-        const confirmStub = sinon.stub(
-          Blockly.dialog.TEST_ONLY,
-          'confirmInternal',
-        );
+        const confirmStub = sinon.stub(window, 'confirm');
         this.workspace.newBlock('text');
         this.deleteOption.callback(this.scope);
         this.clock.runAll();
 
         sinon.assert.notCalled(confirmStub);
         assert.equal(this.workspace.getTopBlocks(false).length, 0);
+
+        confirmStub.restore();
       });
 
       test('Has correct label for multiple blocks', function () {

tests/mocha/dialog_test.js

@@ -0,0 +1,168 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {assert} from '../../node_modules/chai/chai.js';
+import {
+  sharedTestSetup,
+  sharedTestTeardown,
+} from './test_helpers/setup_teardown.js';
+
+suite('Dialog utilities', function () {
+  setup(function () {
+    sharedTestSetup.call(this);
+    this.workspace = Blockly.inject('blocklyDiv', {});
+  });
+
+  teardown(function () {
+    sharedTestTeardown.call(this);
+    Blockly.dialog.setAlert();
+    Blockly.dialog.setPrompt();
+    Blockly.dialog.setConfirm();
+    Blockly.dialog.setToast();
+  });
+
+  test('use the browser alert by default', function () {
+    const alert = sinon.stub(window, 'alert');
+    Blockly.dialog.alert('test');
+    assert.isTrue(alert.calledWith('test'));
+    alert.restore();
+  });
+
+  test('support setting a custom alert handler', function () {
+    const alert = sinon.spy();
+    Blockly.dialog.setAlert(alert);
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.alert(message, callback);
+    assert.isTrue(alert.calledWith('test', callback));
+  });
+
+  test('do not call the browser alert if a custom alert handler is set', function () {
+    const browserAlert = sinon.stub(window, 'alert');
+
+    const alert = sinon.spy();
+    Blockly.dialog.setAlert(alert);
+    Blockly.dialog.alert(test);
+    assert.isFalse(browserAlert.called);
+
+    browserAlert.restore();
+  });
+
+  test('use the browser confirm by default', function () {
+    const confirm = sinon.stub(window, 'confirm');
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isTrue(confirm.calledWith(message));
+    confirm.restore();
+  });
+
+  test('support setting a custom confirm handler', function () {
+    const confirm = sinon.spy();
+    Blockly.dialog.setConfirm(confirm);
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isTrue(confirm.calledWith('test', callback));
+  });
+
+  test('do not call the browser confirm if a custom confirm handler is set', function () {
+    const browserConfirm = sinon.stub(window, 'confirm');
+
+    const confirm = sinon.spy();
+    Blockly.dialog.setConfirm(confirm);
+    const callback = () => {};
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isFalse(browserConfirm.called);
+
+    browserConfirm.restore();
+  });
+
+  test('invokes the provided callback with the confirmation response', function () {
+    const confirm = sinon.stub(window, 'confirm').returns(true);
+    const callback = sinon.spy();
+    const message = 'test';
+    Blockly.dialog.confirm(message, callback);
+    assert.isTrue(callback.calledWith(true));
+    confirm.restore();
+  });
+
+  test('use the browser prompt by default', function () {
+    const prompt = sinon.stub(window, 'prompt');
+    const callback = () => {};
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isTrue(prompt.calledWith(message, defaultValue));
+    prompt.restore();
+  });
+
+  test('support setting a custom prompt handler', function () {
+    const prompt = sinon.spy();
+    Blockly.dialog.setPrompt(prompt);
+    const callback = () => {};
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isTrue(prompt.calledWith('test', defaultValue, callback));
+  });
+
+  test('do not call the browser prompt if a custom prompt handler is set', function () {
+    const browserPrompt = sinon.stub(window, 'prompt');
+
+    const prompt = sinon.spy();
+    Blockly.dialog.setPrompt(prompt);
+    const callback = () => {};
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isFalse(browserPrompt.called);
+
+    browserPrompt.restore();
+  });
+
+  test('invokes the provided callback with the prompt response', function () {
+    const prompt = sinon.stub(window, 'prompt').returns('something');
+    const callback = sinon.spy();
+    const message = 'test';
+    const defaultValue = 'default';
+    Blockly.dialog.prompt(message, defaultValue, callback);
+    assert.isTrue(callback.calledWith('something'));
+    prompt.restore();
+  });
+
+  test('use the built-in toast by default', function () {
+    const message = 'test toast';
+    Blockly.dialog.toast(this.workspace, {message});
+    const toast = this.workspace
+      .getInjectionDiv()
+      .querySelector('.blocklyToast');
+    assert.isNotNull(toast);
+    assert.equal(toast.textContent, message);
+  });
+
+  test('support setting a custom toast handler', function () {
+    const toast = sinon.spy();
+    Blockly.dialog.setToast(toast);
+    const message = 'test toast';
+    const options = {message};
+    Blockly.dialog.toast(this.workspace, options);
+    assert.isTrue(toast.calledWith(this.workspace, options));
+  });
+
+  test('do not use the built-in toast if a custom toast handler is set', function () {
+    const builtInToast = sinon.stub(Blockly.Toast, 'show');
+
+    const toast = sinon.spy();
+    Blockly.dialog.setToast(toast);
+    const message = 'test toast';
+    Blockly.dialog.toast(this.workspace, {message});
+    assert.isFalse(builtInToast.called);
+
+    builtInToast.restore();
+  });
+});

tests/mocha/index.html

@@ -192,6 +192,7 @@
       import './contextmenu_items_test.js';
       import './contextmenu_test.js';
       import './cursor_test.js';
+      import './dialog_test.js';
       import './dropdowndiv_test.js';
       import './event_test.js';
       import './event_block_change_test.js';
@@ -260,6 +261,7 @@
       import './shortcut_registry_test.js';
       import './touch_test.js';
       import './theme_test.js';
+      import './toast_test.js';
       import './toolbox_test.js';
       import './tooltip_test.js';
       import './trashcan_test.js';

tests/mocha/test_helpers/workspace.js

@@ -100,9 +100,7 @@ export function testAWorkspace() {
 
     test('deleteVariableById(id2) one usage', function () {
       // Deleting variable one usage should not trigger confirm dialog.
-      const stub = sinon
-        .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-        .callsArgWith(1, true);
+      const stub = sinon.stub(window, 'confirm').returns(true);
       this.workspace.deleteVariableById('id2');
 
       sinon.assert.notCalled(stub);
@@ -110,13 +108,13 @@ export function testAWorkspace() {
       assert.isNull(variable);
       assertVariableValues(this.workspace, 'name1', 'type1', 'id1');
       assertBlockVarModelName(this.workspace, 0, 'name1');
+
+      stub.restore();
     });
 
     test('deleteVariableById(id1) multiple usages confirm', function () {
       // Deleting variable with multiple usages triggers confirm dialog.
-      const stub = sinon
-        .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-        .callsArgWith(1, true);
+      const stub = sinon.stub(window, 'confirm').returns(true);
       this.workspace.deleteVariableById('id1');
 
       sinon.assert.calledOnce(stub);
@@ -124,13 +122,13 @@ export function testAWorkspace() {
       assert.isNull(variable);
       assertVariableValues(this.workspace, 'name2', 'type2', 'id2');
       assertBlockVarModelName(this.workspace, 0, 'name2');
+
+      stub.restore();
     });
 
     test('deleteVariableById(id1) multiple usages cancel', function () {
       // Deleting variable with multiple usages triggers confirm dialog.
-      const stub = sinon
-        .stub(Blockly.dialog.TEST_ONLY, 'confirmInternal')
-        .callsArgWith(1, false);
+      const stub = sinon.stub(window, 'confirm').returns(false);
       this.workspace.deleteVariableById('id1');
 
       sinon.assert.calledOnce(stub);
@@ -139,6 +137,8 @@ export function testAWorkspace() {
       assertBlockVarModelName(this.workspace, 0, 'name1');
       assertBlockVarModelName(this.workspace, 1, 'name1');
       assertBlockVarModelName(this.workspace, 2, 'name2');
+
+      stub.restore();
     });
   });
 

tests/mocha/toast_test.js

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {assert} from '../../node_modules/chai/chai.js';
+import {
+  sharedTestSetup,
+  sharedTestTeardown,
+} from './test_helpers/setup_teardown.js';
+
+suite('Toasts', function () {
+  setup(function () {
+    sharedTestSetup.call(this);
+    this.workspace = Blockly.inject('blocklyDiv', {});
+    this.toastIsVisible = (message) => {
+      const toast = this.workspace
+        .getInjectionDiv()
+        .querySelector('.blocklyToast');
+      return !!(toast && toast.textContent === message);
+    };
+  });
+
+  teardown(function () {
+    sharedTestTeardown.call(this);
+  });
+
+  test('can be shown', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message});
+    assert.isTrue(this.toastIsVisible(message));
+  });
+
+  test('can be shown only once per session', function () {
+    const options = {
+      message: 'texas toast',
+      id: 'test',
+      oncePerSession: true,
+    };
+    Blockly.Toast.show(this.workspace, options);
+    assert.isTrue(this.toastIsVisible(options.message));
+    Blockly.Toast.hide(this.workspace);
+    Blockly.Toast.show(this.workspace, options);
+    assert.isFalse(this.toastIsVisible(options.message));
+  });
+
+  test('oncePerSession is ignored when false', function () {
+    const options = {
+      message: 'texas toast',
+      id: 'some id',
+      oncePerSession: true,
+    };
+    Blockly.Toast.show(this.workspace, options);
+    assert.isTrue(this.toastIsVisible(options.message));
+    Blockly.Toast.hide(this.workspace);
+    options.oncePerSession = false;
+    Blockly.Toast.show(this.workspace, options);
+    assert.isTrue(this.toastIsVisible(options.message));
+  });
+
+  test('can be hidden', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message});
+    assert.isTrue(this.toastIsVisible(message));
+    Blockly.Toast.hide(this.workspace);
+    assert.isFalse(this.toastIsVisible(message));
+  });
+
+  test('can be hidden by ID', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, id: 'test'});
+    assert.isTrue(this.toastIsVisible(message));
+    Blockly.Toast.hide(this.workspace, 'test');
+    assert.isFalse(this.toastIsVisible(message));
+  });
+
+  test('hide does not hide toasts with different ID', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, id: 'test'});
+    assert.isTrue(this.toastIsVisible(message));
+    Blockly.Toast.hide(this.workspace, 'test2');
+    assert.isTrue(this.toastIsVisible(message));
+  });
+
+  test('are shown for the designated duration', function () {
+    const clock = sinon.useFakeTimers();
+
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, duration: 3});
+    for (let i = 0; i < 3; i++) {
+      assert.isTrue(this.toastIsVisible(message));
+      clock.tick(1000);
+    }
+    assert.isFalse(this.toastIsVisible(message));
+
+    clock.restore();
+  });
+
+  test('default to polite assertiveness', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {message, id: 'test'});
+    const toast = this.workspace
+      .getInjectionDiv()
+      .querySelector('.blocklyToast');
+
+    assert.equal(
+      toast.getAttribute('aria-live'),
+      Blockly.Toast.Assertiveness.POLITE,
+    );
+  });
+
+  test('respects assertiveness option', function () {
+    const message = 'texas toast';
+    Blockly.Toast.show(this.workspace, {
+      message,
+      id: 'test',
+      assertiveness: Blockly.Toast.Assertiveness.ASSERTIVE,
+    });
+    const toast = this.workspace
+      .getInjectionDiv()
+      .querySelector('.blocklyToast');
+
+    assert.equal(
+      toast.getAttribute('aria-live'),
+      Blockly.Toast.Assertiveness.ASSERTIVE,
+    );
+  });
+});