Contents:

Introduction

In this assignment, you will build a TypeScript version of the popular puzzle Connect the Dots using Facebook's Javascript Framework React. This assignment is not directly related to any of the previous assignments, but will help you build a strong React foundation which will help you in the next assignment.

Important Instructions

As with previous assignments, if you have a question you should ask the course staff for assistance and support. In this assignment (and this assignment only), we encourage you to perform web searches if you are stuck and need assistance. However, you must note the following:

Getting Set Up to Develop with React

We recommend you use IntelliJ Ultimate as opposed to IntelliJ Community for this and the next assignment. IntelliJ Ultimate has much better IDE support for writing Javascript/TypeScript, and so likely will be more helpful for your development. There are free student licenses for IntelliJ Ultimate available, linked from the resources page for this course. Note that you can still complete this assignment with IntelliJ Community edition, it will simply be less helpful with auto-completing and error-checking.

The commands and installation procedures for Node and NPM (which are what we're using to manage our React development environment) are the same for both Windows and macOS/Linux users. First, navigate to the Node.js homepage and install the "LTS" version of Node.js. This will also install the correct version of NPM automatically. Windows users should make sure that the “Add to PATH” option is enabled during the installation process.

macOS users running modern versions of macOS may get a warning about the installer not coming from a “verified developer.” To resolve this, open System Preferences and navigate to Security & Privacy > General. There, you'll be able to click “Open” to run the Node/NPM installer.

Once you have Node.js and NPM installed, restart IntelliJ (if it's open). Next, you need to install React and all of the other things that React needs to work correctly. We provided hw-dots/package.json, which tells NPM how to install React and where to find all the things it needs. All you need to do is run the installation. From the project root directory (which you can get to by opening the terminal window in IntelliJ), run the following two commands: 

cd hw-dots
npm install

The first navigates you to the hw-dots directory, which you'll need to run all your commands inside. The second tells NPM to read the package.json file and perform the installation for you. It's not uncommon for this installation to take 15+ minutes, depending on the speed of your network connection and your computer, so don't worry if it seems to be taking a while. You may get a few warnings and messages, but nothing particularly tragic should be printed to the screen. You'll only need to do this installation once for each place you have your repository cloned. To test your installation, run npm start. This will run your React application, which currently only has the starter code that we provided. When it's done starting up, a browser window will automatically open the website.

If the browser didn't automatically open, or the wrong browser opened, you can manually navigate to http://localhost:3000 to view your site. Now that the React server is up and running, you can edit the code and the website will auto-reload without you having to stop and re-start the React server. When you're done with development, you can stop the running react server by clicking in the terminal window where it's running and pressing Control-C.

Unfortunately, the CSE Linux machines (both the lab linux machines and the attu cluster) are running a version of CentOS that doesn't support the correct version of Node/NPM for our purposes. For this reason, you should work on your assignment on either the Windows lab computers (labs are closed), the CSE Windows Virtual Machine/Remote Desktop, or on your own personal machine. (Windows, macOS, and Linux will all work fine as long as you are an administrator on the computer so you can install the correct version of the software we're using.)

In addition to the steps above, we require that you use an up-to-date version of the Chrome web browser. Other browsers have varying compatibility and have the potential to complicate grading or cause your code to fail when being run in the grading environment.

We recommend using React Developer Tools, a Chrome Extension created by Facebook. Using this tool will help you debug your React code as you work on this assignment and the next assignment. It can help you view props and state of your components and trace how data is flowing between your components. It will also provide warnings in the console about common mistakes that it finds in your code.

Resources

The Connect the Dots Graphical User Interface(GUI) is written using HTML and TypeScript, principally with the React framework.

To learn about HTML, see the W3 Schools HTML tutorial.

To learn about JavaScript (the basis for TypeScript), see the MDN JavaScript tutorial.

To learn about TypeScript (a superset of Javascript that adds type information), see the official TypeScript website.

We will not go deeply into either JavaScript/TS or HTML, so use these resources only to learn what you need and do not feel obligated to study them in depth.

We've created a React handout that explains some of the finer points of React and will guide you as you implement your applications in the next two assignments. It's especially important that you read the Advanced User Interface section before beginning this assignment - many of the concepts discussed there are used throughout this assignment.

We've published a live demo of a completed version of this assignment that's based on the staff solution. This is not intended to be a complete example of “the correct way to do things” — please always follow this spec above all else. In particular, you do not have to have your input validation work the same way as the example: you need to have input validation, but it doesn't have to match the example exactly, you're free to design it as you choose.

Creating a User Interface using React

You will write a User Interface(UI) to let users run a version of a Connect the Dots drawing puzzle.

You will write the UI in *.tsx files under hw-dots/src. You may create additional files as needed and may edit provided files. Each file may contain no more than a single React class/component. Be sure to add any new files to your repository as you commit your changes. You may also add .ts files if you choose to write any other code (i.e. helper functions) that aren't a part of a specific component. (You aren't required to have separate .ts files if you don't want to.)

The interface provided by the staff has the following elements:

Important Note

Much of the functionality in this starter code is only half-written, often with hard-coded values instead of actual interactivity. The code is full of unused variables and half-implemented functions for you to complete. For example, the “edges” text box currently can't be edited at all. It's your job to read and modify the provided code to complete the functionality of the application.

The starter code is half-written. This means you will need to add or change props, state, and functions in the components. You are not required to keep our existing code - please change it if you can think of a better design.

A Recommended Path through this Assignment

  1. Read ALL of the code. Twice. Make sure you understand it. We can't stress that enough. If you make sure you fully understand how the data is flowing (or not flowing when it should be), it will be much easier to complete this assignment. We recommend you experiment by making small changes to the code to test your understanding and make sure things are behaving the way you think they should be. If it helps, draw a picture of how the components are related to each other and how the data travels between them. Once you are confident you understand how the basic functionality of this application works, you can move on to the next step. If you're not sure what's going on, re-read the Advanced User Interface section in the React handout, look at lecture or section materials, or ask a question on the discussion board or in office hours.
  2. Currently, the text field inside GridSizePicker is able to be edited. The actual number that was entered into the text box is stored in the state of App, in state.gridSize. A string version of it is passed down to be displayed by the GridSizePicker through its value prop, and a callback function that updates the state is passed into the GridSizePicker through the onChange prop. Whenever the text field has a change, the GridSizePicker's onInputChange method is called, which parses the text inside the text field into an integer, then calls the onChange function it got as a prop from App to tell it about the new data. (This is similar to the standard “fully-controlled component” model described in the Advanced User Interface section of the React handout.) The current value of the grid size is also passed as a prop to Grid, so it can be used when rendering the grid onto the canvas. It's your job to make use of that information so the Grid component automatically changes the way it's displayed based on the current grid size.
    1. Update the render method in Grid to make sure the “Current Grid Size: X” text properly displays the current value of the gridSize prop.
    2. Update the getCoordinates method in Grid so that it dynamically calculates the coordinates of all the points that need to be drawn by redraw, and returns those points in the same format as getCoordinates already does. If the current gridSize is 5, it should return an array of 25 2-element arrays, each with an x and y coordinate representing the location of one of the 25 points in a 5x5 grid. The exact spacing and arrangement of the grid is your choice, but it should be centered, and fill a reasonable amount of space on the image (i.e. not be tiny, but also fit completely within the canvas). Note that the drawCircle function already takes care of making the circles smaller or bigger depending on how many there are, though you're welcome to modify this behavior if you have a better idea. :)
    3. Your Grid component should react (get it? React? :P) immediately to the changing text field, no button presses or other user action should be required. (Lifecycle methods might be helpful here.)
    4. You should provide additional input validation beyond what is already provided. The text area's max and min attributes prevent using the arrow-buttons inside the text field from going beyond the limit, but there's nothing stopping the user from typing whatever number they want into the text field unless you add code to protect your application from bad input. You should notify the user of their error and give them a chance to correct whatever incorrect input they caused. Your application should support at least a grid of 100x100, but be careful to create a sensible maximum — your app can crash if it tries to calculate and draw a 1000x1000 grid of 10^6 dots, for example.
    5. It should be possible to completely delete the text in the grid size picker without causing an error. This is for usability reasons, it's frustrating for a user to be unable to delete everything in a text box so they can enter a new value. You will likely need to test if the string is the empty string in your parsing/validation logic and have a special case for this. It's ok for the grid to have "size zero" (be blank) for this time, or just keep using whatever size the grid used to be before the user cleared the text box. In order to do this, you might need to separate the string being displayed in the text box from the number that's tracking the current grid size in App. (Right now, the string being displayed in the text box is just the result of calling toString on App's gridSize state.) For example, you could have a piece of state (a string) in GridSizePicker that keeps track of the current string in the text box, and then use the App state to track the current grid size, as it's already doing. That way, you could have App's current grid size be zero, for example, while the GridSizePicker's displayed string is the empty string.
    6. You now have the basic functionality of the Grid component complete. This is a good point to commit and save your work before continuing.
  3. Examine how the data flows to and from the textfield inside GridSizePicker. Consider where the data is stored, and how it's passed between components as needed. Much of this machinery doesn't exist for the text area inside the EdgeList, which is why that text area currently can't be edited. You can use your understanding of GridSizePicker to aid in your development of similar code for EdgeList's text area. Your program should have the following functionality with regards to edges:
    1. You'll want to make the text field editable so the user can enter edges. This will involve creating state to store the current contents of the text box, and then using that state with the onchange and value props of the textarea.
    2. When the “Draw” button is pressed, you should parse the string into an object/array/whatever-works-for-you that represents all the edges to be drawn. When Draw is pressed, the entire contents of the grid is replaced by whatever is currently in the edge list.
    3. You'll need to get that edge data to the Grid component somehow, and add to the rendering/drawing code inside the Grid component so it draws lines in addition to the grid itself, according to the edge data entered by the user. This probably will involve creating state/props in a number of components, to move the data between them. The Canvas Drawing section of the React handout might be a helpful reference for this.
    4. Edge data should be entered by the user in the following format: 
      x1,y1 x2,y2 COLOR
      Each line in the text box represents one line that should be drawn on the grid. The X and Y coordinates in this field correspond to the X and Y indices of specific grid dots, and the lines should be drawn connecting two grid dots. Be careful not to confuse grid point (1, 1) with canvas pixel coordinate (1, 1). The upper-left grid dot is defined to be (0, 0). The maximum reasonable coordinate depends on the current grid size.
    5. You should validate all user input and reject improperly formatted input by displaying a helpful message to the user. Nowhere in your program should it be possible for a user to cause a JS error to appear on the screen, even if the user is trying to cause an error. Note: You can assume that the color input is well-formed as long as it's some kind of string: you don't need to make sure that it actually spells out a reasonable color.
    6. As an example, on a 4x4 grid the following input in EdgeList would produce a black square connecting the innermost four points in the grid (once the Draw button has been pressed). 
      1,1 1,2 black
1,1 2,1 black
1,2 2,2 black
2,1 2,2 black
    7. Think about where you want to handle the parsing logic: do you want to do all the parsing inside EdgeList and then only hand the completed/parsed data object up to App, OR do you want to hand the raw string from the text box up to App and let App do the parsing, OR should App pass that string to Grid and let Grid do the parsing? (Or something else entirely?) Think about cohesion/coupling and what makes sense from a design perspective. There are choices you can make at this step that can make implementing the rest of the application easier for yourself — the benefits of good design!
    8. Remember, you're allowed to modify any of the provided code anywhere in the assignment: this includes adding props that you need, removing props that you don't need, adding state variables, constructors, functions, or any other code to any components. If you really want to, you can also add your own components as part of your solution, though that's not necessary for a clean solution to this assignment.
  4. Update the clear button so that it clears all the edges being drawn to the Grid. It is your choice whether you want to clear the contents of the text box, or just clear some internal piece of data so the Grid stops drawing the edges. If you'd like, you can also make the clear button reset the Grid size back to 4x4, though this isn't required.

Using TypeScript

It can be tempting, when the TypeScript compiler is complaining about something, to simply add the any annotation to whatever is causing your problem to get the compiler to be quiet. There are plenty of reasonable uses for any, but you should always carefully evaluate whether you are simply masking a bug before you use it.

For example, it's generally fine (in this course) to replace complex names that come from React or HTML with any to keep the code simple. There's a trade-off here - the code may be somewhat simpler, but (a) you get less help from the TypeScript compiler, since it can't catch bugs that it can't see, and (b) you get less help from IntelliJ, since it doesn't know what kind of object it's dealing with. It's up to you to make a choice about what types you want to write out, and what types you'll leave as any. TypeScript is a tool - the more you use it, the more it will help you.

At a minimum, you should attempt to use explicit types for the following:

One note - some TypeScript compiler errors can be long or confusing. When you encounter errors like this, resist the urge to randomly change the code in the hopes that it will go away. By not understanding the error behind what you wrote, you are making yourself more likely to make the same mistake in the future, and you're robbing yourself the opportunity to understand why the compiler said what it said, and why the code that was there had a problem. When you're faced with an error you don't understand, here are some tips for figuring out what's going on:

Testing

Writing automated tests for GUIs is important, but it can be difficult and usually involves special frameworks that are beyond the scope of this course. For this reason, you are not required to write unit tests or a test driver. We will test your solution by running your main program.

If you would like to run a sanity check on your code to ensure that your code works as expected, use the following statements to draw edges in your application and make sure the image matches the provided image below. You should set your grid to be size 100 for this test. 

82,46 83,46 red
83,46 84,47 red
84,47 84,48 red
84,48 83,49 red
83,49 82,49 red
82,49 81,48 red
81,48 81,47 red
81,47 82,46 red

82,46 81,44 orangered
83,46 84,44 orangered
84,47 86,46 orangered
84,48 86,49 orangered
83,49 84,51 orangered
82,49 81,51 orangered
81,48 79,49 orangered
81,47 79,46 orangered
An example image with a drawing of a sun.

UI Enhancements

You are responsible for creating a GUI that performs the required tasks, and that is easy to use and intuitive. You are permitted, but not required, to be creative and improve upon this basic design. (Don't do this until after you have completed all of the basic requirements for the assignment.)

Projects that go substantially beyond the basic requirements will receive a small amount of extra credit. Here are a few suggested enhancements (you're welcome to come up with your own too):

Additional functionality should augment, not replace, the requirements of the assignment. Your internal code does not need to be structured like the provided code; you're welcome to throw it all out and re-write the app from scratch if you'd like, but the external functionality must be identical. Please record all additional functionality you attempted to add in hw-dots/extras.txt. Extra Credit points will not be awarded for functionality that is not documented in that specific file.

Time management: there are lots of fun, interesting things that could be done here. Be sure though to get the main requirements done, and be sure you don't wind up attempting more than you have time to accomplish. Simple, meets the requirements, and works, is much better than very elaborate, super interesting, but not done or still buggy at the end.

Hints

Node/NPM/React Installation Issues

Javascript Hints

How to Turn In Your Homework

./gradlew validate will not validate your homework assignment. The staff strongly recommends you use the latest, standard version of Google Chrome to test your code. Your UI must load when we use Google Chrome to visit http://localhost:3000 after running npm start from hw-dots/.

There are no new files that you must submit as part of the assignment, unless you add any new files yourself. Make sure to commit any changes and additional files you create. Don't forget to note any additional functionality in extras.txt.

Refer to the assignment submission handout for complete turnin instructions. You should use the tag hw8-final to mark your final submission.

There is no GitLab validation for this assignment, so not having a pipeline when you submit the tag is normal.