Merge branch 'toast' into april-ut

Author: microbit-matt-hillsdon

src/actions/clipboard.ts

@@ -19,7 +19,7 @@ import type {BlockSvg, WorkspaceSvg} from 'blockly';
 import {Navigation} from '../navigation';
 import {ScopeWithConnection} from './action_menu';
 import {getShortActionShortcut} from '../shortcut_formatting';
-import {toast} from '../toast';
+import {clearPasteHints, showCopiedHint} from '../hints';
 
 const KeyCodes = blocklyUtils.KeyCodes;
 const createSerializedKey = ShortcutRegistry.registry.createSerializedKey.bind(
@@ -279,10 +279,7 @@ export class Clipboard {
       if (navigationState === Constants.STATE.FLYOUT) {
         this.navigation.focusWorkspace(workspace);
       }
-      toast(workspace, {
-        message: `Copied. Press ${getShortActionShortcut('paste')} to paste.`,
-        duration: 7000,
-      });
+      showCopiedHint(workspace);
     }
     return copied;
   }
@@ -359,6 +356,8 @@ export class Clipboard {
    */
   private pasteCallback(workspace: WorkspaceSvg) {
     if (!this.copyData || !this.copyWorkspace) return false;
+    clearPasteHints(workspace);
+
     const pasteWorkspace = this.copyWorkspace.isFlyout
       ? workspace
       : this.copyWorkspace;

src/actions/enter.ts

@@ -21,9 +21,12 @@ import type {
 
 import * as Constants from '../constants';
 import type {Navigation} from '../navigation';
-import {getShortActionShortcut} from '../shortcut_formatting';
 import {Mover} from './mover';
-import {toast} from '../toast';
+import {
+  showConstrainedMovementHint,
+  showHelpHint,
+  showUnconstrainedMoveHint,
+} from '../hints';
 
 const KeyCodes = BlocklyUtils.KeyCodes;
 
@@ -104,9 +107,7 @@ export class EnterAction {
     } else if (nodeType === ASTNode.types.BLOCK) {
       const block = curNode.getLocation() as Block;
       if (!this.tryShowFullBlockFieldEditor(block)) {
-        const shortcut = getShortActionShortcut('list_shortcuts');
-        const message = `Press ${shortcut} for help on keyboard controls`;
-        toast(workspace, {message});
+        showHelpHint(workspace);
       }
     } else if (curNode.isConnection() || nodeType === ASTNode.types.WORKSPACE) {
       this.navigation.openToolboxOrFlyout(workspace);
@@ -152,30 +153,14 @@ export class EnterAction {
     workspace.getCursor()?.setCurNode(ASTNode.createBlockNode(newBlock)!);
     this.mover.startMove(workspace);
 
-    const sessionItemKey = 'isToastInsertFromFlyoutShown';
-    if (!this.sessionStorageIfPossible[sessionItemKey]) {
-      const enter = getShortActionShortcut(
-        Constants.SHORTCUT_NAMES.EDIT_OR_CONFIRM,
-      );
-      const message = `Use the arrow keys to move, then ${enter} to accept the position`;
-      toast(workspace, {message});
-      this.sessionStorageIfPossible[sessionItemKey] = 'true';
-    }
-  }
-
-  private sessionStorageIfPossible = this.getSessionStorageIfPossible();
-
-  /**
-   * Gets session storage if possible.
-   * If session storage is not possible, fallback on internal tracker, which
-   * resets per intialisation instead of per session.
-   */
-  private getSessionStorageIfPossible() {
-    try {
-      return window.sessionStorage;
-    } catch (e) {
-      // Handle possible SecurityError, absent window.
-      return {} as Record<string, string>;
+    const isTopLevelBlock =
+      !newBlock.outputConnection &&
+      !newBlock.nextConnection &&
+      !newBlock.previousConnection;
+    if (isTopLevelBlock) {
+      showUnconstrainedMoveHint(workspace, false);
+    } else {
+      showConstrainedMovementHint(workspace);
     }
   }
 

src/actions/mover.ts

@@ -17,7 +17,7 @@ import * as Constants from '../constants';
 import {Direction, getXYFromDirection} from '../drag_direction';
 import {KeyboardDragStrategy} from '../keyboard_drag_strategy';
 import {Navigation} from '../navigation';
-import {blocks} from 'node_modules/blockly/core/serialization';
+import {clearMoveHints} from '../hints';
 
 /**
  * The distance to move an item, in workspace coordinates, when
@@ -141,6 +141,7 @@ export class Mover {
    */
   finishMove(workspace: WorkspaceSvg) {
     this.removeMoveIndicator();
+    clearMoveHints(workspace);
 
     const info = this.moves.get(workspace);
     if (!info) throw new Error('no move info for workspace');
@@ -166,6 +167,7 @@ export class Mover {
    */
   abortMove(workspace: WorkspaceSvg) {
     this.removeMoveIndicator();
+    clearMoveHints(workspace);
 
     const info = this.moves.get(workspace);
     if (!info) throw new Error('no move info for workspace');

src/hints.ts

@@ -0,0 +1,104 @@
+/**
+ * Centralises hints that we show.
+ *
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {WorkspaceSvg} from 'blockly';
+import {SHORTCUT_NAMES} from './constants';
+import {getShortActionShortcut} from './shortcut_formatting';
+import {clearToast, toast} from './toast';
+
+const unconstrainedMoveHintId = 'unconstrainedMoveHint';
+const constrainedMoveHintId = 'constrainedMoveHint';
+const copiedHintId = 'copiedHint';
+const helpHintId = 'helpHint';
+
+/**
+ * Nudge the user to use unconstrained movement.
+ *
+ * @param workspace Workspace.
+ * @param force Set to show it even if previously shown.
+ */
+export function showUnconstrainedMoveHint(
+  workspace: WorkspaceSvg,
+  force = false,
+) {
+  const enter = getShortActionShortcut(SHORTCUT_NAMES.EDIT_OR_CONFIRM);
+  const modifier = navigator.platform.startsWith('Mac') ? '⌥' : 'Ctrl';
+  const message = `Hold ${modifier} and use arrow keys to move freely, then ${enter} to accept the position`;
+  toast(workspace, {
+    message,
+    id: unconstrainedMoveHintId,
+    oncePerSession: !force,
+  });
+}
+
+/**
+ * Nudge the user to move a block that's in move mode.
+ *
+ * @param workspace Workspace.
+ */
+export function showConstrainedMovementHint(workspace: WorkspaceSvg) {
+  const enter = getShortActionShortcut(SHORTCUT_NAMES.EDIT_OR_CONFIRM);
+  const message = `Use the arrow keys to move, then ${enter} to accept the position`;
+  toast(workspace, {message, id: constrainedMoveHintId, oncePerSession: true});
+}
+
+/**
+ * Clear active move-related hints, if any.
+ *
+ * @param workspace The workspace.
+ */
+export function clearMoveHints(workspace: WorkspaceSvg) {
+  clearToast(workspace, constrainedMoveHintId);
+  clearToast(workspace, unconstrainedMoveHintId);
+}
+
+/**
+ * Nudge the user to paste after a copy.
+ *
+ * @param workspace Workspace.
+ */
+export function showCopiedHint(workspace: WorkspaceSvg) {
+  toast(workspace, {
+    message: `Copied. Press ${getShortActionShortcut('paste')} to paste.`,
+    duration: 7000,
+    id: copiedHintId,
+  });
+}
+
+/**
+ * Clear active paste-related hints, if any.
+ *
+ * @param workspace The workspace.
+ */
+export function clearPasteHints(workspace: WorkspaceSvg) {
+  // TODO: cut?
+  clearToast(workspace, copiedHintId);
+}
+
+/**
+ * Nudge the user to open the help.
+ *
+ * @param workspace The workspace.
+ */
+export function showHelpHint(workspace: WorkspaceSvg) {
+  const shortcut = getShortActionShortcut('list_shortcuts');
+  const message = `Press ${shortcut} for help on keyboard controls`;
+  const id = helpHintId;
+  toast(workspace, {message, id});
+}
+
+/**
+ * Clear the help hint.
+ *
+ * @param workspace The workspace.
+ */
+export function clearHelpHint(workspace: WorkspaceSvg) {
+  // TODO: We'd like to do this in MakeCode too as we override.
+  // Could have an option for showing help in the plugin?
+  clearToast(workspace, helpHintId);
+}

src/index.ts

@@ -7,6 +7,7 @@
 import * as Blockly from 'blockly/core';
 import {NavigationController} from './navigation_controller';
 import {getFlyoutElement, getToolboxElement} from './workspace_utilities';
+import {clearHelpHint} from './hints';
 
 /** Options object for KeyboardNavigation instances. */
 export interface NavigationOptions {
@@ -283,7 +284,7 @@ export class KeyboardNavigation {
    * Toggle visibility of a help dialog for the keyboard shortcuts.
    */
   toggleShortcutDialog(): void {
-    this.navigationController.shortcutDialog.toggle();
+    this.navigationController.shortcutDialog.toggle(this.workspace);
   }
 
   /**

src/keyboard_drag_strategy.ts

@@ -14,6 +14,7 @@ import {
   utils,
 } from 'blockly';
 import {Direction, getDirectionFromXY} from './drag_direction';
+import {showUnconstrainedMoveHint} from './hints';
 
 // Copied in from core because it is not exported.
 interface ConnectionCandidate {
@@ -69,6 +70,12 @@ export class KeyboardDragStrategy extends dragging.BlockDragStrategy {
     } else {
       // Handle the case when unconstrained drag was far from any candidate.
       this.searchNode = null;
+
+      if (this.isConstrainedMovement()) {
+        // @ts-expect-error private field
+        const workspace = this.workspace;
+        showUnconstrainedMoveHint(workspace, true);
+      }
     }
   }
 

src/shortcut_dialog.ts

@@ -11,6 +11,7 @@ import {
   getLongActionShortcutsAsKeys,
   upperCaseFirst,
 } from './shortcut_formatting';
+import {clearHelpHint} from './hints';
 
 /**
  * Class for handling the shortcuts dialog.
@@ -64,7 +65,12 @@ export class ShortcutDialog {
     }
   }
 
-  toggle() {
+  toggle(workspace: Blockly.WorkspaceSvg) {
+    clearHelpHint(workspace);
+    this.toggleInternal();
+  }
+
+  toggleInternal() {
     if (this.modalContainer && this.shortcutDialog) {
       // Use built in dialog methods.
       if (this.shortcutDialog.hasAttribute('open')) {
@@ -132,7 +138,7 @@ export class ShortcutDialog {
       // Can we also intercept the Esc key to dismiss.
       if (this.closeButton) {
         this.closeButton.addEventListener('click', (e) => {
-          this.toggle();
+          this.toggleInternal();
         });
       }
     }
@@ -161,8 +167,8 @@ export class ShortcutDialog {
     /** List all of the currently registered shortcuts. */
     const announceShortcut: ShortcutRegistry.KeyboardShortcut = {
       name: Constants.SHORTCUT_NAMES.LIST_SHORTCUTS,
-      callback: () => {
-        this.toggle();
+      callback: (workspace) => {
+        this.toggle(workspace);
         return true;
       },
       keyCodes: [Blockly.utils.KeyCodes.SLASH],

src/toast.ts

@@ -1,9 +1,27 @@
 import {WorkspaceSvg} from 'blockly';
 
+const storage = (() => {
+  try {
+    return window.sessionStorage;
+  } catch (e) {
+    // Handle possible SecurityError, absent window.
+    return {} as Record<string, string>;
+  }
+})();
+
 /**
  * Toast options.
  */
 export interface ToastOptions {
+  /**
+   * Message id.
+   */
+  id?: string;
+  /**
+   * Flag to show the toast once per session only.
+   * Subsequent calls are ignored.
+   */
+  oncePerSession?: boolean;
   /**
    * Message text.
    */
@@ -15,6 +33,8 @@ export interface ToastOptions {
   duration?: number;
 }
 
+const className = 'blocklyToast';
+
 /**
  * Shows a message as a toast positioned over the workspace.
  *
@@ -31,12 +51,26 @@ export interface ToastOptions {
  * @param options Options.
  */
 export function toast(workspace: WorkspaceSvg, options: ToastOptions): void {
+  if (options.oncePerSession && options.id) {
+    if (!options.id) {
+      throw new Error('Must pass id to use oncePerSession');
+    }
+    const key = 'blocklyKeyboardNavShownHints';
+    const value = storage[key] ?? '[]';
+    const shown = JSON.parse(value);
+    if (shown.includes(options.id)) {
+      return;
+    }
+    shown.push(options.id);
+    storage[key] = JSON.stringify(shown);
+  }
+
   const {message, duration = 10000} = options;
-  const className = 'blocklyToast';
-  workspace.getInjectionDiv().querySelector(`.${className}`)?.remove();
+  clearToast(workspace);
 
   const foregroundColor = 'black';
   const toast = document.createElement('div');
+  toast.dataset.toastId = options.id;
   toast.className = className;
   toast.setAttribute('role', 'status');
   toast.setAttribute('aria-live', 'polite');
@@ -107,6 +141,21 @@ export function toast(workspace: WorkspaceSvg, options: ToastOptions): void {
   setToastTimeout();
 }
 
+/**
+ * Clear a toast, e.g. in response to a user action.
+ *
+ * @param workspace The workspace
+ * @param id The toast id, or undefined for any toast.
+ */
+export function clearToast(workspace: WorkspaceSvg, id?: string) {
+  const toast = workspace
+    .getInjectionDiv()
+    .querySelector(`.${className}`) as HTMLElement | null;
+  if (toast && (!id || id === toast.dataset.toastId)) {
+    toast.remove();
+  }
+}
+
 function icon(innerHTML: string, style: Partial<CSSStyleDeclaration> = {}) {
   const icon = document.createElement('svg');
   assignStyle(icon, style);