Rewrite the Adagrams demo app using Ink #38

mmcknett · 2022-06-11T04:51:14Z

Adagrams demo game rewrite

Motivation and Architecture

This PR is a rewrite of the Adagrams demo-game. It includes an Architectural Decision Record explaining the motivation and details of the decision to rewrite. If this PR is accepted and merged, consider that ADR also accepted.

The new application is written with Ink, which allows you to build CLI applications with React. Several prominent CLI tools, including jest, depend on this framework. The application's architecture is documented in README files in its folders, and is intended to walk inquisitive students through the organization and design of the app, in an attempt to fulfill the goals of the ADR.

Testing

You can test the branch locally. If you've already cloned the repo, you can add my fork as a remote, install, and run:

git remote add mmcknett https://github.com/mmcknett/js-adagrams.git
git fetch mmcknett
git checkout mmcknett/mm-ink-demo-app
yarn install
yarn run demo-game

The unit tests should pass except for adagrams, since that isn't implemented:

yarn test

You should be able to test the demo with a working Adagrams solution by merging c17/solution into it. Just don't push the merge commit. If this PR is accepted, I will rebase the solutions onto main.

git merge c17/solution

PR work tracking

Items remaining prior to PR publish:

Documentation, including...
- Motivation (i.e. why do this rewrite?)
- Brief overview of Ink
- Brief overview of the app architecture, especially focusing on the reducer and some of the more esoteric parts like the Timer
Final pass-through to make sure the React is canonical and represents best practices that we would want inquisitive students to emulate.
- ~~Also want to investigate whether babel is still necessary for transpilation (e.g. of the js modules)~~
Automated tests
- ~~current tests were all manual; I was having trouble thinking about how to test Ink apps~~
- Ink testing seems to have some issues running useEffect prior to stdin.write calls. I was able to generally work around the issue by rerendering after any changes to the React tree could be expected, but it seems likely there is either some trouble between Ink and recent versions of React or that I missed some necessary testing setup.
Rebase on main
Update root repo README for the new game

Also move some existing state to it.

The menu to accept configuration and move on is not yet present, but there is state for the three options and the ability to update them.

Player entry was briefly flashing 1 + the number of players after entering the last player's name.

Ink complains the app has a memory leak if you change state after dispatching an action that unmounts the component.

This is a more common name for this type of function.

This includes a flag in the reducer that lets you start the game without setup.

The menu was cumbersome without callbacks, so I made the MenuEntry's second parameter optionally be a callback instead of a string.

Any other action resets the error state.

The win screen had a bunch of logic for calculating scores using Adagrams and the game state. This is similar to what redux calls "selectors". Extract those "selectors" into a class so that additional logic can be added. The extraction was done under test, but the tests rely on Adagrams working correctly, so I'm not merging them as-is.

Not only was it sketchy, React doesn't allow it and throws an error.

Proxy default values were not all working. The Real functions themselves were defined, they were just returning `undefined`.

- Explain Ink a little more - Document Screens, with initial wireframes and an MVC exploration - Document Timer - Copyediting

Reading screens first probably makes more sense.

I also added a bunch of discussion on MVC, then put the whole section behind a collapsible TL;DR.

I used the term "middleware" incorrectly. Middleware is a higher-order function applied to the `dispatch` function. The structures I had called "middleware" in the documentation are actually higher-order reducers. They modify the reducer, but still guarantee a state is returned and do not produce side-effects. Middleware wrapping the dispatcher allows for side-effects and behavior that does not produce state modifications.

mmcknett force-pushed the mm-ink-demo-app branch from 732db8d to 622dd88 Compare July 13, 2022 07:34

mmcknett changed the base branch from c17/solution to main July 13, 2022 07:35

mmcknett added 28 commits July 13, 2022 00:38

Basic Ink app with a Main Menu

cb87e2a

Add a help screen

9d9e83c

Create a reducer for game state

925a34f

Also move some existing state to it.

Add a Go Back button to the help screen

d4987a6

Make 'How To' full screen and center the button

dfb4f7a

help -> how-to

d523607

Add the game setup screen

1d8f106

The menu to accept configuration and move on is not yet present, but there is state for the three options and the ability to update them.

Add input validation for the number of players

9b75b1a

Validate number of rounds and seconds per turn

9e255c0

Add a menu to the Game Setup screen

3dacd08

Add TODO for context API

367cba5

Create the player entry screen

df3bc46

fix: Player entry flash

3550d8c

Player entry was briefly flashing 1 + the number of players after entering the last player's name.

Add reset & rematch action types

02405b0

fix: memory leak warning

1f2b503

Ink complains the app has a memory leak if you change state after dispatching an action that unmounts the component.

Interceptor -> Middleware

22a4c6f

This is a more common name for this type of function.

Extract the NumberField component

4c08630

Use inverse for button selected

9ceeff0

Buttons can have color

440bb89

refactor: if chain -> switch

0f3862a

Create a screen for the main Game

54e6731

EnterPlayers was missing propTypes

375db30

Create context for game state and share error view

1c4fbf2

Force player names to be unique

54190fd

Add a timer and turn/round counter

e1e2f5f

This includes a flag in the reducer that lets you start the game without setup.

Add an empty win screen.

383694c

The menu was cumbersome without callbacks, so I made the MenuEntry's second parameter optionally be a callback instead of a string.

CLEAR_ERROR unneeded

8b74a8d

Any other action resets the error state.

Add guessing and reject already-guessed words

9534d49

mmcknett added 20 commits July 13, 2022 00:38

docs: Copy-edit the ADR

a766252

test: Add tests to get full coverage of reducer.js

f5ef6bb

Add NumberField unit tests

5ebe4d1

feat: Add the round high scores

11a248c

fix: support backspace in number field

21c53b1

test: update basic ui tests

16a423c

fix: Remove unneeded error logging

cce3b82

fix: Don't dispatch as a setState side effect

fe46348

Not only was it sketchy, React doesn't allow it and throws an error.

fix: Update all menus to use callbacks instead of ids

d92d9bf

tiny: Update the debugging data

81bb4e8

Mock Adagrams for reducer tests

ebeefb0

fix: Eliminate unique key error

8be4614

Remove vorpal demo game

f658baa

fix: Use highestScoreFrom in WinScreenInfo

1b16d4a

refactor: Move adagrams adapter

5516676

refactor: Rename app -> ui for clarity

0b0afa4

refactor: Clarify that the Proxy pattern is used

3ccf198

fix: Proxy

c5c2105

Proxy default values were not all working. The Real functions themselves were defined, they were just returning `undefined`.

doc: Add readmes for the demo game and state

4e8ed0f

mmcknett force-pushed the mm-ink-demo-app branch from 622dd88 to 4e8ed0f Compare July 13, 2022 07:44

mmcknett added 2 commits July 13, 2022 13:00

refactor: App can be jsx

0b7135f

docs: More documentation

eaf73be

- Explain Ink a little more - Document Screens, with initial wireframes and an MVC exploration - Document Timer - Copyediting

mmcknett marked this pull request as ready for review July 13, 2022 21:17

mmcknett added 6 commits July 13, 2022 21:44

docs: Fix typo and use em dashes

53cfaf6

docs: Update root README

103852d

docs: Copyedit the Demo Game root docs

1d1a4ad

docs: reorder bullet points

e424d8a

Reading screens first probably makes more sense.

docs: Copyedit screens readme.

f0fc05f

I also added a bunch of discussion on MVC, then put the whole section behind a collapsible TL;DR.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite the Adagrams demo app using Ink #38

Rewrite the Adagrams demo app using Ink #38

mmcknett commented Jun 11, 2022 •

edited

Loading

Rewrite the Adagrams demo app using Ink #38

Are you sure you want to change the base?

Rewrite the Adagrams demo app using Ink #38

Conversation

mmcknett commented Jun 11, 2022 • edited Loading

Adagrams demo game rewrite

Motivation and Architecture

Testing

PR work tracking

mmcknett commented Jun 11, 2022 •

edited

Loading