Initial tour implementation (#321)

* Trigger data collection tour when connected
* Trigger train model tour once first recording is added
* Trigger testing model tour after training

Author: microbit-matt-hillsdon

lang/ui.en.json

@@ -11,6 +11,14 @@
     "defaultMessage": "Developed in partnership with <link>Center for Computational Thinking and Design, Aarhus University</link>",
     "description": "Title of about dialog"
   },
+  "accelerometer-image-alt": {
+    "defaultMessage": "micro:bit showing X axis going across the front, Y axis going down and up, Z axis going back to front",
+    "description": "Alt text for image showing the board-relative directions of the X/Y/Z dimensions of the micro:bit accelerometer"
+  },
+  "actions-label": {
+    "defaultMessage": "Actions",
+    "description": "Label for Actions"
+  },
   "actions.reconnect": {
     "defaultMessage": "Reconnect",
     "description": ""
@@ -512,7 +520,7 @@
     "description": ""
   },
   "content.data.dataDescription": {
-    "defaultMessage": "Multiple samples of movement data collected in approximately 2 second bursts.",
+    "defaultMessage": "Short collections of movement data lasting approximately 2 seconds. Your data samples are only stored on your computer, they do not get sent to anyone else.",
     "description": ""
   },
   "content.data.deleteAction": {
@@ -604,15 +612,15 @@
     "description": ""
   },
   "content.model.output.output.descriptionBody": {
-    "defaultMessage": "What the micro:bit will do when each action is detected.",
+    "defaultMessage": "These MakeCode blocks will show icons for each action detected when you transfer your code and model to a micro:bit.",
     "description": ""
   },
   "content.model.output.output.descriptionTitle": {
     "defaultMessage": "Output",
     "description": ""
   },
   "content.model.output.recognitionPoint": {
-    "defaultMessage": "Recognition Point:",
+    "defaultMessage": "Recognition point:",
     "description": ""
   },
   "content.trainer.description": {
@@ -740,7 +748,7 @@
     "description": ""
   },
   "footer.helpContent": {
-    "defaultMessage": "This graph shows movement data from the micro:bit’s accelerometer in real time. Try moving your connected micro:bit to see the X, Y and Z axes change.",
+    "defaultMessage": "This graph shows movement data from the micro:bit's accelerometer in real time. Try moving your data collection micro:bit to see the X, Y and Z axes change. Each coloured line represents a different direction (dimension) you are moving the micro:bit in.",
     "description": ""
   },
   "footer.helpHeader": {
@@ -803,6 +811,10 @@
     "defaultMessage": "Language",
     "description": "Language option text"
   },
+  "live-data-graph": {
+    "defaultMessage": "Live data graph",
+    "description": "Title for live data graph"
+  },
   "loading": {
     "defaultMessage": "loading",
     "description": ""
@@ -964,8 +976,8 @@
     "description": "Reload page button text"
   },
   "reset-to-default-action": {
-    "defaultMessage": "Reset to default",
-    "description": "Reset to default button text"
+    "defaultMessage": "Reset to default blocks",
+    "description": "Reset to default blocks button text"
   },
   "resources": {
     "defaultMessage": "Resources",
@@ -1039,6 +1051,10 @@
     "defaultMessage": "Join our testing community",
     "description": ""
   },
+  "skip-tour-action": {
+    "defaultMessage": "Skip tour",
+    "description": "Skip tour button text"
+  },
   "software-versions": {
     "defaultMessage": "Software versions",
     "description": "Software versions text"
@@ -1067,6 +1083,82 @@
     "defaultMessage": "Testing model",
     "description": "Testing model page title"
   },
+  "tour-collectData-addActions-content": {
+    "defaultMessage": "Decide what your other actions will be and what you will name them. You need at least 2 actions with 3 data samples to train the model. Your data samples are only stored on your computer, they do not get sent to anyone else.",
+    "description": "Tour step description"
+  },
+  "tour-collectData-addActions-title": {
+    "defaultMessage": "Add more actions",
+    "description": "Tour step title"
+  },
+  "tour-collectData-afterFirst-content": {
+    "defaultMessage": "To train the machine learning model you need at least 3 data samples for 2 different actions.",
+    "description": "Tour step description"
+  },
+  "tour-collectData-afterFirst-title": {
+    "defaultMessage": "You’ve recorded your first sample!",
+    "description": "Tour step title"
+  },
+  "tour-collectData-collectMore-content": {
+    "defaultMessage": "Record more samples for this action. Collecting more samples should result in a better machine learning model.",
+    "description": "Tour step description"
+  },
+  "tour-collectData-collectMore-title": {
+    "defaultMessage": "Collect more data samples",
+    "description": "Tour step title"
+  },
+  "tour-collectData-trainModel-content": {
+    "defaultMessage": "When you have collected enough data samples you can train the machine learning model. You can come back later to remove or add more data and re-train to make the model more reliable.",
+    "description": "Tour step description"
+  },
+  "tour-dataSamples-actions-content": {
+    "defaultMessage": "An action is the type of movement you want the machine learning tool to recognise e.g. ‘waving’ or ‘clapping’. Decide what your first action will be, name it and then start recording data samples.",
+    "description": "Tour step content"
+  },
+  "tour-dataSamples-connected-content": {
+    "defaultMessage": "Now you can start collecting data samples to train a machine learning (ML) model to recognise different movements.",
+    "description": "Tour step content"
+  },
+  "tour-dataSamples-connected-title": {
+    "defaultMessage": "Your data collection micro:bit is connected!",
+    "description": "Tour step title"
+  },
+  "tour-dataSamples-liveGraph-content": {
+    "defaultMessage": "The graph shows movement data from the micro:bit’s accelerometer. Move your data collection micro:bit and see how the graph changes.",
+    "description": "Tour step content"
+  },
+  "tour-testModel-afterTrain-content": {
+    "defaultMessage": "Now test your machine learning model. Try each action by moving your data collection micro:bit. Does the model detect each action?",
+    "description": "Tour step description"
+  },
+  "tour-testModel-afterTrain-title": {
+    "defaultMessage": "You’ve trained an ML model!",
+    "description": "Tour step title"
+  },
+  "tour-testModel-certaintyRecognition-content": {
+    "defaultMessage": "The meter shows how confident the model is that you are doing each action. Move the slider to adjust the recognition point, or threshold.",
+    "description": "Tour step description"
+  },
+  "tour-testModel-certaintyRecognition-title": {
+    "defaultMessage": "Certainty and recognition point",
+    "description": "Tour step title"
+  },
+  "tour-testModel-editInMakeCode-content": {
+    "defaultMessage": "Open your project in MakeCode to download the program and your machine learning model to a micro:bit. You can add more blocks to create your own programs using your model.",
+    "description": "Tour step description"
+  },
+  "tour-testModel-estimatedAction-content": {
+    "defaultMessage": "The action the model estimates you are currently doing is shown above the micro:bit icon for that action.",
+    "description": "Tour step description"
+  },
+  "tour-testModel-makeCodeBlocks-content": {
+    "defaultMessage": "These MakeCode blocks will show icons for each action detected when you transfer your code and model to a micro:bit.",
+    "description": "Tour step description"
+  },
+  "tour-testModel-makeCodeBlocks-title": {
+    "defaultMessage": "Microsoft MakeCode blocks",
+    "description": "Tour step title"
+  },
   "train-model-intro-description": {
     "defaultMessage": "Ask the computer to use your training samples to train the machine learning model to recognise different actions.",
     "description": "Train model step home page description"

src/components/AddDataGridWalkThrough.tsx

@@ -1,9 +1,9 @@
-import { GridItem, HStack, Image, Text, VStack } from "@chakra-ui/react";
+import { GridItem, HStack, Text, VStack } from "@chakra-ui/react";
 import { FormattedMessage } from "react-intl";
 import { GestureData } from "../model";
-import upCurveArrowImage from "../images/curve-arrow-up.svg";
-import greetingEmojiWithArrowImage from "../images/greeting-emoji-with-arrow.svg";
 import DataRecordingGridItem from "./DataRecordingGridItem";
+import GreetingEmojiWithArrow from "./GreetingEmojiWithArrow";
+import UpCurveArrow from "./UpCurveArrow";
 
 interface AddDataGridWalkThrough {
   gesture: GestureData;
@@ -19,12 +19,7 @@ const AddDataGridWalkThrough = ({
       {gesture.name.length === 0 ? (
         <GridItem h="120px">
           <VStack m={0} p={2} w={200} transform="translate(-30px, 40px)">
-            <Image
-              w="120px"
-              h="103px"
-              src={greetingEmojiWithArrowImage}
-              alt=""
-            />
+            <GreetingEmojiWithArrow w="120px" h="103px" color="brand.500" />
             <Text textAlign="center">
               <FormattedMessage id="content.data.addActionWalkThrough" />
             </Text>
@@ -46,7 +41,7 @@ const AddDataGridWalkThrough = ({
               transform="translateX(65px)"
               w="calc(100% - 65px)"
             >
-              <Image w="60px" h="93px" src={upCurveArrowImage} alt="" />
+              <UpCurveArrow w="60px" h="93px" color="brand.500" />
               <Text w={200} textAlign="center">
                 <FormattedMessage id="content.data.addRecordingWalkThrough" />
               </Text>

src/components/CertaintyThresholdGridItem.tsx

@@ -13,6 +13,7 @@ import {
 } from "@chakra-ui/react";
 import { useCallback, useMemo } from "react";
 import { FormattedMessage, useIntl } from "react-intl";
+import { tourElClassname } from "../tours";
 import PercentageDisplay from "./PercentageDisplay";
 import PercentageMeter from "./PercentageMeter";
 
@@ -54,6 +55,7 @@ const CertaintyThresholdGridItem = ({
         width="fit-content"
         borderWidth={1}
         borderColor="transparent"
+        className={tourElClassname.certaintyThreshold}
       >
         <CardBody
           display="flex"

src/components/CodeViewCard.tsx

@@ -5,6 +5,7 @@ import {
   Project,
 } from "@microbit/makecode-embed/react";
 import { memo } from "react";
+import { tourElClassname } from "../tours";
 
 interface CodeViewCardProps {
   project: Project;
@@ -22,7 +23,13 @@ const CodeViewCard = ({ project }: CodeViewCardProps) => {
       borderColor="brand.500"
       justifyContent="center"
     >
-      <Card w="full" h="full" p={5} objectFit="contain">
+      <Card
+        w="full"
+        h="full"
+        p={5}
+        objectFit="contain"
+        className={tourElClassname.makeCodeCodeView}
+      >
         <MakeCodeBlocksRendering
           code={project}
           layout={BlockLayout.Flow}

src/components/CodeViewGridItem.tsx

@@ -7,6 +7,7 @@ import { memo, useMemo } from "react";
 import { generateProject } from "../makecode/utils";
 import { GestureData } from "../model";
 import { useStore } from "../store";
+import { tourElClassname } from "../tours";
 
 interface CodeViewGridItemProps {
   gesture: GestureData;
@@ -38,6 +39,7 @@ const CodeViewGridItem = ({
           minW="400px"
           width="fit-content"
           justifyContent="center"
+          className={tourElClassname.makeCodeCodeView}
         >
           <Box width={width} py={2} px={2} overflow="hidden">
             <MakeCodeBlocksRendering

src/components/DataRecordingGridItem.tsx

@@ -10,10 +10,11 @@ import {
 import { useCallback, useRef } from "react";
 import { useIntl } from "react-intl";
 import { useConnectionStage } from "../connection-stage-hooks";
-import { GestureData } from "../model";
 import RecordIcon from "../images/record-icon.svg?react";
-import RecordingGraph from "./RecordingGraph";
+import { GestureData } from "../model";
 import { useStore } from "../store";
+import { tourElClassname } from "../tours";
+import RecordingGraph from "./RecordingGraph";
 
 interface DataRecordingGridItemProps {
   data: GestureData;
@@ -52,6 +53,7 @@ const DataRecordingGridItem = ({
           width="fit-content"
           borderColor={selected ? "brand.500" : "transparent"}
           borderWidth={1}
+          className={tourElClassname.recordDataSamplesCard}
         >
           <CardBody display="flex" flexDirection="row" p={1} gap={3}>
             <HStack w="8.25rem" justifyContent="center">

src/components/DefaultPageLayout.tsx

@@ -17,8 +17,9 @@ import { useNavigate } from "react-router";
 import { TOOL_NAME } from "../constants";
 import { flags } from "../flags";
 import { useProject } from "../hooks/project-hooks";
-import { SaveStep } from "../model";
+import { SaveStep, TrainModelDialogStage } from "../model";
 import { SessionPageId } from "../pages-config";
+import Tour from "../pages/Tour";
 import { useSettings, useStore } from "../store";
 import { createHomePageUrl, createSessionPageUrl } from "../urls";
 import ActionBar from "./ActionBar";
@@ -57,6 +58,8 @@ const DefaultPageLayout = ({
   const intl = useIntl();
   const navigate = useNavigate();
   const isEditorOpen = useStore((s) => s.isEditorOpen);
+  const stage = useStore((s) => s.trainModelDialogStage);
+
   const { saveHex } = useProject();
   const [settings] = useSettings();
   const toast = useToast();
@@ -103,13 +106,12 @@ const DefaultPageLayout = ({
 
   return (
     <>
-      {/* Suppress connection and train dialogs when MakeCode editor is open */}
-      {!isEditorOpen && (
-        <>
-          <ConnectionDialogs />
-          <TrainModelDialogs />
-        </>
+      {/* Suppress dialogs to prevent overlapping dialogs */}
+      {!isEditorOpen && stage === TrainModelDialogStage.Closed && (
+        <ConnectionDialogs />
       )}
+      {!isEditorOpen && <TrainModelDialogs />}
+      {!isEditorOpen && stage === TrainModelDialogStage.Closed && <Tour />}
       <DownloadDialogs />
       <SaveDialogs />
       <VStack

src/components/GestureNameGridItem.tsx

@@ -9,10 +9,11 @@ import {
 } from "@chakra-ui/react";
 import { useCallback } from "react";
 import { useIntl } from "react-intl";
+import { useStore } from "../store";
+import { tourElClassname } from "../tours";
 import { MakeCodeIcon } from "../utils/icons";
 import LedIcon from "./LedIcon";
 import LedIconPicker from "./LedIconPicker";
-import { useStore } from "../store";
 
 interface GestureNameGridItemProps {
   name: string;
@@ -83,6 +84,7 @@ const GestureNameGridItem = ({
         borderWidth={selected ? 1 : 0}
         onClick={onSelectRow}
         position="relative"
+        className={tourElClassname.dataSamplesActionCard}
       >
         {!readOnly && onDeleteAction && (
           <CloseButton

src/components/GreetingEmojiWithArrow.tsx

@@ -0,0 +1,31 @@
+import { Icon } from "@chakra-ui/react";
+
+interface GreetingEmojiWithArrowProps {
+  w: string;
+  h: string;
+  color?: string;
+}
+
+const GreetingEmojiWithArrow = ({
+  w,
+  h,
+  color,
+}: GreetingEmojiWithArrowProps) => {
+  return (
+    <Icon w={w} h={h} viewBox="0 0 40 31.424875" color={color}>
+      <path
+        d="M 105.80677,104.76545 A 12.303125,12.303125 0 0 0 90.928702,96.869948 l 0.66753,-1.30567 a 0.51964167,0.51964167 0 0 0 -0.22795,-0.70714 0.51964167,0.51964167 0 0 0 -0.707136,0.22795 l -1.235843,2.41917 a 0.51990625,0.51990625 0 0 0 0.227951,0.70713 l 2.417743,1.2359 a 0.53234167,0.53234167 0 0 0 0.70714,-0.22795 0.51990625,0.51990625 0 0 0 -0.227955,-0.70713 L 91.287,97.866588 a 11.201135,11.201135 0 0 1 13.50055,7.211022 0.54689375,0.54689375 0 0 0 0.27325,0.3067 0.6429375,0.6429375 0 0 0 0.40109,0.0441 0.48709792,0.48709792 0 0 0 0.3098,-0.2422 0.52916667,0.52916667 0 0 0 0.0347,-0.42094"
+        fill="currentColor"
+        clipPath="url(#clipPath1)"
+        display="inline"
+        transform="matrix(1.1240682,0,0,1.1240682,-100.45299,-106.55292)"
+      />
+      <path
+        fill="currentColor"
+        d="m 20.482081,29.956698 c -0.946933,0.02373 -1.806825,-0.47303 -2.229983,-1.288273 -0.06728,-0.129623 -0.164653,-0.380133 -0.208188,-0.535614 l -0.01776,-0.06343 0.531437,-0.07469 0.531437,-0.07469 0.02115,0.06295 c 0.07312,0.217669 0.279373,0.48328 0.496971,0.639986 0.34441,0.248029 0.681415,0.321744 1.106727,0.242082 0.313052,-0.05864 0.537089,-0.18098 0.758756,-0.414348 0.196462,-0.206832 0.354616,-0.549227 0.377681,-0.817659 l 0.0088,-0.102324 0.530723,-0.07459 0.530724,-0.07459 1.43e-4,0.0747 c 0.001,0.523308 -0.130746,0.994505 -0.387281,1.385096 -0.303034,0.461387 -0.725611,0.78725 -1.257363,0.969594 -0.203606,0.06982 -0.589432,0.140666 -0.793962,0.145793 z M 14.935754,26.11049 C 13.154492,26.215391 11.529805,25.608555 10.328702,24.389713 9.0939929,23.136769 8.4689853,21.24571 8.6759065,19.388921 c 0.1167817,-1.04793 0.500206,-2.017793 1.1260509,-2.848321 0.3839756,-0.509554 0.7936766,-0.90173 1.3220506,-1.265499 0.61022,-0.420116 1.274848,-0.715598 2.038498,-0.906278 0.315066,-0.07867 10.209673,-1.468941 10.542298,-1.481276 1.167234,-0.04328 2.248553,0.206167 3.197321,0.737597 1.924577,1.078007 3.070974,3.209328 2.986059,5.551524 -0.03793,1.046194 -0.356733,2.076315 -0.907281,2.93161 -0.841472,1.307256 -2.149563,2.200682 -3.742218,2.555933 -0.269729,0.06016 -10.029244,1.430161 -10.302931,1.446279 z m 9.880667,-3.962235 c 0.735633,-0.201619 1.368721,-0.63128 1.827775,-1.240469 0.773781,-1.026845 0.90565,-2.409818 0.340308,-3.568971 -0.105176,-0.215648 -0.349956,-0.579334 -0.510764,-0.758877 -0.690198,-0.770607 -1.673157,-1.189177 -2.69908,-1.149341 -0.251513,0.0098 -9.725215,1.341208 -9.969677,1.401147 -1.390244,0.340868 -2.430743,1.518672 -2.590015,2.931793 -0.03898,0.345804 -0.031,0.577622 0.03303,0.960425 0.05584,0.333818 0.09556,0.478722 0.202706,0.739431 0.532242,1.295071 1.844656,2.149988 3.244491,2.113487 0.07914,-0.0021 2.24332,-0.29839 5.030174,-0.688747 4.280878,-0.599625 4.91621,-0.691958 5.091056,-0.739878 z m -10.36065,-0.732646 c -0.361972,-0.04241 -0.697468,-0.247762 -0.898963,-0.550245 -0.230237,-0.34563 -0.280143,-0.73156 -0.146249,-1.130973 0.06645,-0.198224 0.248934,-0.452733 0.413298,-0.576421 0.344822,-0.259487 0.770372,-0.33055 1.179512,-0.196966 0.147374,0.04812 0.203388,0.07842 0.354317,0.191689 0.153465,0.115171 0.193866,0.156446 0.280672,0.286741 0.139022,0.208671 0.193978,0.36377 0.215783,0.608988 0.0103,0.115819 0.0098,0.235942 -0.0013,0.300864 -0.07767,0.456117 -0.376294,0.826326 -0.799368,0.990978 -0.149562,0.05821 -0.43593,0.0943 -0.597744,0.07534 z m 9.309591,-1.308377 c -0.343839,-0.04029 -0.677273,-0.235675 -0.877632,-0.514288 -0.121252,-0.168608 -0.172015,-0.28824 -0.21345,-0.50303 -0.04657,-0.241405 -0.03656,-0.405943 0.03915,-0.64359 0.04614,-0.144844 0.07594,-0.200783 0.183241,-0.343974 0.141887,-0.189352 0.268866,-0.296369 0.471385,-0.397278 0.111247,-0.05543 0.154159,-0.06673 0.367323,-0.09669 0.213163,-0.02996 0.257526,-0.03093 0.379742,-0.0083 0.222326,0.04115 0.374141,0.109062 0.560044,0.250534 0.192921,0.146813 0.318982,0.310834 0.40865,0.531706 0.129905,0.319985 0.112812,0.726301 -0.04372,1.03926 -0.133147,0.266204 -0.391678,0.499271 -0.676987,0.610308 -0.149562,0.05821 -0.43593,0.0943 -0.597744,0.07534 z"
+      />
+    </Icon>
+  );
+};
+
+export default GreetingEmojiWithArrow;