Forem: Adam Dawkins

Building Hangman with Hyperapp - Part 5

Adam Dawkins — Tue, 21 Jan 2020 23:37:50 +0000

Finishing touches

Let's start to tidy this up. First we'll add some styling. Hyperapp elements can take a style object, much like React, but for our simple styling purposes, we'll just add a stylesheet and some classes.

/* style.css */
body {
  box-sizing: border-box;
  font-family: 'Helvetica Neue', Helvetica, sans-serif;
  padding: 1rem 2rem;
  background: #f0f0f0;
}
h1 {
  font-size: 5rem;
  margin: 1rem 0;
}

.subtitle {
  font-size: 2rem;
}

.word {
  font-size: 4rem;
  display: flex;
  justify-content: center;
}

.accent {
  color: #fccd30;
}

.input {
  border: 2px solid black;
  font-size: 36px;
  width: 1.5em;
  margin: 0 1em;
  text-align: center;
}

.guesses {
  font-size: 2rem;
  display: flex;
}

.guess {
  margin: 0 .5em;
}

.linethrough {
  text-decoration: line-through;
}

.header {
  display: flex;
  align-items: baseline;
  justify-content: space-between;
}

Staying Alive

Before we add the classes, I wanted to show the number of lives left to the user as part of the displaying of the bad guesses, just using a simple heart emoji.

To this, firstly, I renamed badGuesses to getBadGuesses for clarity, and then passed just the guesses to our BadGuesses view instead of the whole state:

// HELPERS

const getBadGuesses = state =>
  state.guesses.filter(guess => !isInWord(guess, state));

const isGameOver = state => getBadGuesses(state).length >= MAX_BAD_GUESSES;


// VIEWS
const BadGuesses = guesses => [
  h2({}, "Your Guesses:"),
  ul(
    { class: "guesses" },
    guesses.map(guess => li({ class: "guess" }, guess))
  )
];


// THE APP
app({
  //....
  view: state =>
    //...
    BadGuesses(getBadGuesses(state));
});

With that done, we now need to count how many lives are left and output that many hearts, replacing the lost lives with the bad guesses:

// UTILITIES

// returns an array of all the numbers between start and end.
// range(2, 5) => [2, 3, 4, 5]
const range = (start, end) => {
  const result = [];
  let i = start;
  while (i <= end) {
    result.push(i);
    i++;
  }

  return result;
};

// VIEWS
const BadGuesses = guesses =>
  div({ class: "guesses" }, [
    range(1, MAX_BAD_GUESSES - guesses.length).map(() =>
      span({ class: "guess" }, "♥️")
    ),
    guesses.map(guess => span({ class: "guess linethrough" }, guess))
  ]);

Now we should see our lives output before the guesses. Let's add the rest of the classes now, with a bit of re-arrangement.

// VIEWS

const WordLetter = (letter, guessed) =>
  span({ class: "letter" } // ...

const Word = state =>
  div(
    { class: "word" },
    // ....
  );


// THE APP

app({
  init: [
    {
      word: [],
      guesses: [],
      guessedLetter: ""
    },
    getWord()
  ],
  view: state =>
    div({}, [
      div({ class: "header" }, [
        div([h1("Hangman."), h2({ class: "subtitle" }, "A hyperapp game")]),
        div({}, BadGuesses(getBadGuesses(state)))
      ]),
      isGameOver(state)
      ? h2({}, `Game Over! The word was "${state.word.join("")}"`)
      : isVictorious(state)
      ? [h2({}, "You Won!"), Word(state)]
      : [Word(state), UserInput(state.guessedLetter)]
    ]),
  node: document.getElementById("app")
});

There, things are looking much better.

A bug

We have a tiny bug to fix. When the page refreshes, you can see the 'You Won!' message for a split-second. This has come in because our word is being retrieved remotely. It's a simple fix, we just check the word is there first.

app({
// ...

  view: state =>
    div({}, [
      div({ class: "header" }, [
        div([h1("Hangman."), h2({ class: "subtitle" }, "A hyperapp game")]),
        div({}, BadGuesses(getBadGuesses(state)))
      ]),
      state.word.length > 0 &&
        (isGameOver(state)
          ? h2({}, `Game Over! The word was "${state.word.join("")}"`)
          : isVictorious(state)
          ? [h2({}, "You Won!"), Word(state)]
          : [Word(state), UserInput(state.guessedLetter)])
    ]),

    //...
})

By putting this under our header, we don't give the user the illusion of delay, it's fast enough, and the flash is gone.

A Key Ingredient

This is a perfectly serviceable Hangman game in just 131 generous lines of Hyperapp, with an HTTP service being called to get the word.

But one thing could lead to a much better user experience. Why do we need an input field? We could just ask the user to type a letter and take that as their guess.

Let's change the UI first, and then work out how to implement that.

We just need to replace our UserInput with the instruction to type a letter:

: [
    Word(state),
    p(
      { style: { textAlign: "center" } },
      "Type a letter to have a guess."
    )
  ])

Don't forget to subscribe

To respond to key presses anywhere in our application we need to look at the last tool in our core toolset from Hyperapp: Subscriptions. Subscriptions respond to global events and call actions for our app. Examples of subscriptions include:

timers
intervals (to fetch things from servers)
global DOM events.

We'll be subscribing to the keyDown event and calling our GuessLetter Action every time the event is fired.

import { onKeyDown, targetValue, preventDefault } from "@hyperapp/events";

Subscriptions get added to our app function:

  app({
    init: /* ... */,
    view: /* ... */,
    subscriptions: () => [onKeyDown(GuessLetter)],
    node: document.getElementById("app")
  });

We need to make some changes to GuessLetter for this to work. Currently it looks like this:

const GuessLetter = state => ({
  ...state,
  guesses: state.guesses.concat([state.guessedLetter]),
  guessedLetter: ""
});

It takes state, gets our gussedLetter from the state, (we were setting that onInput on our text field) and then adding it to state.guesses.

We don't need that interim step of setting a guessedLetter anymore, so we can remove our SetGuessedLetter Action, and guessedLetter from our initial state.

Ok, so, what's going to get passed GuessedLetter from our onKeyDown subscription? Our current state, and a keyDown event object:

const GuessedLetter = (state, event) =>

We can get the actual key off the event and append it straight to our guesses:

const GuessLetter = (state, event) => ({
  ...state,
  guesses: state.guesses.concat([event.key])
})

Return to sender

It works! But we have a bit of a problem, every key we press is being counted as a guess: numbers, punctuation, even Control and Alt.

Let's check that we have a letter before guessing:

const GuessLetter = (state, event) =>
  // the letter keycodes range from 65-90
  contains(range(65, 90), event.keyCode)
    ? {
        ...state,
        guesses: state.guesses.concat([event.key])
      }
    : state;

We leave our state untouched if the key that's pressed isn't a letter.

More fixes and enhancements

There are just a couple more enhancements and bug fixes we need to make before we're done:

Give the user a way to play again.
Stop letters being guessed after the game has finished
Don't let the user guess the same letter twice - we'll do this simply by ignoring it.

Rinse & repeat.

One of the real joys of working with Hyperapp is that we only have one state going on. To allow a user to play again, we just need to reset the state.

Because we'll want to show our 'play again' button for both victory and game over states, I'm going to put it in it's own View:

// VIEWS

const PlayAgain = () => button({ onclick: ResetGame }, "Play again");

Our ResetGame action just sets everything back to the start, and calls getWord() again to get a new word:

// ACTIONS

const ResetGame = () => [
  {
    guesses: [],
    word: []
  },
  getWord()
];

Now we add our PlayAgain view to the UI and we're golden:

app({
  init: /* ... */,
  view: state =>
    div({}, [
      div({ class: "header" }, [
        div([h1("Hangman."), h2({ class: "subtitle" }, "A hyperapp game")]),
        div({}, BadGuesses(getBadGuesses(state)))
      ]),
      state.word.length > 0 &&
        (isGameOver(state)
          ? [
              h2({}, `Game Over! The word was "${state.word.join("")}"`),
              PlayAgain()
            ]
          : isVictorious(state)
          ? [h2({}, "You Won!"), PlayAgain(), Word(state)]
          : [
              Word(state),
              p(
                { style: { textAlign: "center" } },
                "Type a letter to have a guess."
              )
            ])
    ]),
  subscriptions: /* ... */,
  node: /* ... */
});

A quick refactor

For me, a downside of using @hyperapp/html over jsx is that visualing changes to UI becomes quite difficult. One way to get around this is not to try and treat it like HTML, but as the functions they actually are.

I'm going to split the victorious and game over UIs into their own Views.

// VIEWS

// ...

const GameOver = state => [
  h2({}, `Game Over! The word was "${state.word.join("")}"`),
  PlayAgain()
];

const Victory = state => [h2({}, "You Won!"), PlayAgain(), Word(state)];


// THE APP
app({
  //...
  view: state =>
    div({}, [
      div({ class: "header" }, [
        div([h1("Hangman."), h2({ class: "subtitle" }, "A hyperapp game")]),
        div({}, BadGuesses(getBadGuesses(state)))
      ]),
      state.word.length > 0 &&
        (isGameOver(state)
          ? GameOver(state)
          : isVictorious(state)
          ? Victory(state)
          : [
              Word(state),
              p(
                { style: { textAlign: "center" } },
                "Type a letter to have a guess."
              )
            ])
    ]),

  //...
});

While we're at it, let's move some other parts out into Views that make sense as well:


// THE VIEWS

const Header = state =>
  div({ class: "header" }, [
    div([h1("Hangman."), h2({ class: "subtitle" }, "A hyperapp game")]),
    div({}, BadGuesses(getBadGuesses(state)))
  ]);

const TheGame = state => [
  Word(state),
  p({ style: { textAlign: "center" } }, "Type a letter to have a guess.")
];

// THE APP
app({
  //...
  view: state =>
    div({}, [
      Header(state),
      state.word.length > 0 &&
        (isGameOver(state)
          ? GameOver(state)
          : isVictorious(state)
          ? Victory(state)
          : TheGame(state))
    ]),

  //...
});

There's another refactor you may have noticed here. Our ResetGame action looks exactly the same as our app.init:


const ResetGame = () => [
  {
    word: [],
    guesses: []
  },
  getWord()
];

  init: [
    {
      word: [],
      guesses: []
    },
    getWord()
  ],

Let's move that out and make it clearer than ResetGame literally returns us to our initial state:

// HELPERS

const getInitialState = () => [
  {
    guesses: [],
    word: []
  },
  getWord()
];

// ACTIONS

const ResetGame = getInitialState();

// THE APP
app({
  init: getInitialState(),
  // ...
});

Stop guessing!

Our game has three states it can be in: Playing, Lost, and Won. At the moment we're testing for two of these on the whole state with isGameOver() and isVictorious().

We can use these in GuessLetter to see if we should keep accepting guesses, but there might be a better way. Let's start there anyway, and refactor afterwards:

const GuessLetter = (state, event) =>
  isGameOver(state) ||
  isVictorious(state) ||
  // the letter keycodes range from 65-90
  !contains(range(65, 90), event.keyCode)
    ? state
    : {
        ...state,
        guesses: state.guesses.concat([event.key])
      };

This stops extra guesses being accepted, but I'm not sure it's going to be clearest as to what's going on. We could make this clearer by being more explicit about the state of the game after each guess.

I'd normally do this by setting up a constant that represents all of the states:

const GAME_STATE = {
  PLAYING: 1,
  LOST: 2,
  WON: 3
}

But in this case, we already have two of these states working nicely with our isGameOver() and isVictorious() helpers. For an application this small, I don't think we need can justify all the extra overhead. Let's just add some more helpers to be more explicit about our intentions here.

Expressing it in plain English, we want to allow a guess if the user is still playing and the key they pressed is a letter:

const GuessLetter = (state, event) =>
  isPlaying(state) && keyCodeIsLetter(event.keyCode)
    ? {
        ...state,
        guesses: state.guesses.concat([event.key])
      }
    : state;

That's clearer. And for the helpers...

const isPlaying = state => !(isGameOver(state) || isVictorious(state));

const keyCodeIsLetter = keyCode => keyCode >= 65 && keyCode <= 90;

Our last part of this then is to stop duplicate letters. We'll take the same approach and write in the helper function we'd want in here and then write the actual helper after.

  isPlaying(state) &&
  keyCodeIsLetter(event.keyCode) &&
  isNewLetter(state, event.key)

// HELPERS

const isNewLetter = (state, letter) => !contains(state.guesses, letter);

That's a wrap

And there we have it, Hangman in Hyperapp. If you have any questions or comments you can reach me on Twitter at @adamdawkins or email at adam@dragondrop.uk

This tutorial was originally posted on adamdawkins.uk on 3rd December 2019

Building Hangman with Hyperapp - Part 4

Adam Dawkins — Tue, 21 Jan 2020 23:35:26 +0000

Special Effects

Our Hangman works now, but it's got a bit of a way to go before we'd really want to show it to anyone. Anyway, before we think of ways to jazz it up, let's look back at our original MVP list:

The Computer picks a random word for us to guess
The Player inputs letters to guess the word - done
Like the paper version, correct letters get inserted into the word, incorrect letters get listed elsewhere -done
8 incorrect guesses and the Player loses - done
If the Player fills in the word correctly, they win. - done

We need to do one last thing to complete our initial spec - get the computer to pick a random word.

Talking to the Internet

To get our random word, we're going to make an HTTP call to a server that is going to return as a random word. We could obviously pre-load our app with a list of words, but HTTP calls are so common and useful to make our applications work that we'll do this instead.

I've created an endpoint at https://adamdawkins.uk/randomword.json that will return a random word in the format:

{ "word": "the_random_word" }

To use something from outside our app like this, we need to use something Hyperapp calls 'effects'.

What are effects?

We run programs for their side effects. Likewise, we want our programs to be predictable, easy to compose, test, and parallelize. What if I tell you we can have our cake and eat it too?

Rather than creating a timeout or using fetch to create an HTTP request, actions are allowed to return a description of work that needs done, and Hyperapp will do it behind the scenes. Kind of like the view function returns a specification of the DOM, but doesn't touch the real DOM; an effect describes a side effect: creating an HTTP request, giving focus to an element, saving data to local storage, sending data over a WebSocket, generating a random number, etc., without executing any code!

Now, effects are not built-into Hyperapp, instead we usually import a module that has the effects we need. These modules encapsulate the implementation — the part that tells Hyperapp exactly how to do certain task.

Getting our word from the internet

Let's take a second to remind ourselves what we're trying to do here. The initial state of our application currently looks like this:

app({
init: {
word: "application".split(""),
guesses: [],
guessedLetter: ""
}
//...
//
//
});

We want to replace that hard-coded word "application" with the result of a request to our server: adamdawkins.uk/randomword.json. We can break this down into a series of small tasks:

1) Work out how to make our server call when our application loads
2) Make the server call and send the result to an action
3) Write an action that sets state.word to an array of letters

Let's start with what we know. We know how to write an action that updates the state, we've done this with SetGuessedLetter:

const SetGuessedLetter = (state, letter) => ({
    ...state,
    guessedLetter: letter
    });

Writing an action that updates state.word is almost exactly the same:

const SetWord = (state, word) => ({
    ...state,
    word: word.split("")
    });

Ok, that's number 3 done. All of the 'changes' or actions we've performed so far have been in response to user input. When it comes to Effects, hyperapp has a way of letting us trigger them as the application loads.

Instead of init being just an object representing the initial state of our application, it can be an array containing that object and other effects we want to perform when the application starts. Let's assume we have an action called GetWord and see what that would look like:

app({
init: [
{
word: [],
guesses: [],
guessedLetter: ""
},
getWord()
]
//...
});

So we know how to trigger our effect, and we know how to handle the response to update the state of our application, the last thing we need is the effect itself. How are we going to make this HTTP request and hook it into these actions?

Enter @hyperapp/http.

@hyperapp/http

The @hyperapp/http package gives us a get() function that we can use to perform get requests. It's tailored to wire into hyperapp, it takes a url, an expect format and an action to pass the result to.

For this application, I've put a random word server at https://adamdawkins.uk/randomword.json, and our getWord() function looks like this:

const getWord = () =>
get({
url: `https://adamdawkins.uk/randomword.json`,
expect: "json",
action: SetWord
});

We're done!

And we're done, we have a working version of Hangman in Hyperapp, with an HTTP call, in 116 lines of code.

We'll do one more pass on this is Part 5 to add some styling and think about some different enhancements we could make.

This tutorial was originally posted to adamdawkins.uk on 11th November 2019

Building Hangman with Hyperapp - Part 3

Adam Dawkins — Tue, 21 Jan 2020 23:30:18 +0000

And... Action

In Part 1, we introduced the basics of Hyperapp, and in Part 2, we did a rough sketch of the game of Hangman in code. But we're not going to win any awards just yet - the user can't actually do anything.

To handle interactions with the user, or any other form of event, Hyperapp gives us Actions.

Let's quickly check our spec again:

The Computer picks a random word for us to guess - hard-coded for now
The Player inputs letters to guess the word
Like the paper version, correct letters get inserted into the word, incorrect letters get listed elsewhere
8 incorrect guesses and the Player loses - done
If the Player fills in the word correctly, they win. - done

Before anything else, we're going to want to use the Object rest/spread syntax in Javascript quite a bit with Hyperapp, and we need to add that to our build so parcel can use it.

'Object rest/spread' syntax allows us to want all of the existing properties of an object, and then override the ones we want to change. It reads nicely, but it's also an important way of doing things - whenever we change the state in Hyperapp we actually need to create a new state object, and object spread does just that.

Here's a quick example:

const cat = {
name: 'Larry',
      legs: 4,
      sound: 'meow',
};

const dog = {
  ...cat, // <-- this is the spread we want to support
  sound: 'woof',
};

console.log(dog); // => { name: 'Larry', legs: 4, sounds: 'woof' }

Here our dog kept the name and legs properties of cat, but had it's own sound. We'll use this syntax when we want to return a new version of our state. Let's get it setup.

yarn add babel-plugin-transform-object-rest-spread -d

Put the following in a file called .babelrc:

{
  "plugins": ["transform-object-rest-spread"]
}

Now that's out of the way, we'll start by building a form for our user to enter letters. I've included some basic styling on the input.

import {
  div,
    h1,
    h2,
    ul,
    li,
    span,
    input,
    label,
    form,
    button,
} from '@hyperapp/html';

// ...

// VIEWS
// ...

const UserInput = () =>
form({}, [
    label({for: 'letter'}, 'Your guess:'),
    ,
    input({
type: 'text',
id: 'letter',
maxlength: 1,
style: {
border: '2px solid black',
fontSize: '36px',
width: '1.5em',
margin: '0 1em',
textAlign: 'center',
},
}),
    button({type: 'submit'}, 'Guess!'),
]);

// THE APP
app({
init: {
word: 'application'.split(''),
guesses: [],
},
view: state =>
div(
  {},
  isGameOver(state)
  ? h1({}, `Game Over! The word was "${state.word.join('')}"`)
  : isVictorious(state)
  ? [h1({}, 'You Won!'), Word(state)]
  : [UserInput(), Word(state), BadGuesses(state)],
  ),
node: document.getElementById('app'),
});

Nothing happens... Let's change that with an action.

Actions take the current state, an optional argument and return a new state.

For now, we just want to get our action working when we submit the form, so we'll hardcode the letter 'z' into the guess.

// ACTIONS

const GuessLetter = state => ({
    ...state,
    guesses: state.guesses.concat(['z']),
    });

NB: We use concat here instead of push because Hyperapp always wants a new state object, not a change to the existing one. To put it formally, state in Hyperapp is immutable.

When the GuessLetter action is called, we return the current state, with the letter 'z' added to the guesses.

We want to call this when the user submits the form, or on the submit event.

form({ onSubmit: GuessLetter } // ...
    ```



    This is the gist of it, but it won't actually work yet, because by default, submit events change the URL and refresh the page. We need to stop the default behaviour. We can do that manually, by calling `event.preventDefault()`.




    ```js
    form(
      {
onSubmit: (state, event) => {
event.preventDefault();
return GuessLetter;
},
},

This works, but it introduces a lot of extra boilerplate code all over our view. After all, Javascript UIs are all about events, or we'd just be building in plain HTML. Hyperapp has a @hyperapp/events package that has some useful helper functions for this sort of thing.

Introducing Events

Let's install the package:

yarn add @hyperapp/events

And we'll use the preventDefault helper function from there to stop our form refreshing the page.

    import {preventDefault} from '@hyperapp/events';

    // ...

    // VIEWS

    const UserInput = letter =>
    form(
        {onSubmit: preventDefault(GuessLetter)},
        // ...
        );
    ```



    Now we can repeatedly guess the letter 'z' when we submit the form. Let's take it where we need to go, and capture the user input.


### Capturing User Input
    A key concept in Hyperapp is that there's only one state, and changing the state refreshes our 'loop' around the application. As such, we need to store the user's guessed letter before we submit the form so that we know which letter they've guessed within our `GuessLetter` action. 

    This is where we want our `GuessLetter` action to go:



    ```js
    const GuessLetter = state => ({
        ...state,
        guesses: state.guesses.concat([state.guessedLetter]),
        guessedLetter: '', // reset the letter after the user has guessed it
        });

So, let's add a guessedLetter to our state, set the input to be the same value as it, and change it whenever the value of the input changes.

Add the guessedLetter to our initial state.

//  THE APP
app({
init: {
word: 'application'.split(''),
guesses: [],
guessedLetter: '',
},
// ...
});

Pass the letter to our UserInput view, and set it as the value of the input so that we can display it:

// VIEWS

const UserInput = letter =>
form({onSubmit: preventDefault(GuessLetter)}, [
    label({for: 'letter'}, 'Your guess:'),
    ,
    input({
value: letter,
// ...
},
}),
    button({type: 'submit'}, 'Guess!'),
]);

// THE APP
app({
    // ...
view: // ...

[UserInput(state.guessedLetter), Word(state), BadGuesses(state)],
// ...
});

Change state.guessedLetter when the input changes.

The onInput event we have takes two arguments, the current state, passed in automatically from Hyperapp, and the event that was triggered, so we can use that to to do this action in line:

input({
value: letter,
onInput: (state, event) => ({...state, guessedLetter: event.target.value}),
// ...
},
});

And, just like that, we can now make guesses with an input. We have Hangman.

Getting Better

There's still more work to be done though, we need to make the word random, and we can tidy up some of the user experience. We'll look at those in the next part.

Before you go, let's tidy this up a bit.

We'll take the styling out into a stylesheet: style.css

.input {
border: 2px solid black;
        font-size: 36px;
width: 1.5em;
margin: 0 1em;
        text-align: center;
}

<!-- ... -->
<head>
<link rel="stylesheet" href="./style.css">
</head>
<!-- ... -->

// VIEWS

const UserInput = letter =>
form({/* ... */}, [
    // ...
    input({
      // ...
class: 'input', // add the class 'input'
// remove the style: block
// ...
}),
    // ...
]);

Get rid of the inline action.

// ACTIONS

const SetGuessedLetter = (state, letter) => ({
    ...state,
    guessedLetter: letter,
    });
// VIEWS

input({
    // ...
onInput: (_, event) => [SetGuessedLetter, event.target.value],
});

This is better, but another helper from @hyperapp/events allows us to abstract this pattern of using the event target value

import {preventDefault, targetValue} from '@hyperapp/events';

// VIEWS
input({
    // ...
onInput: [SetGuessedLetter, targetValue],
});

So there we are, 101 lines of code, and we have a working Hangman. Let's make it better by introduction random words - in Part 4.

This tutorial was originally posted to adamdawkins.uk on 7th October 2019

Building Hangman with Hyperapp - Part 2

Adam Dawkins — Tue, 21 Jan 2020 23:27:25 +0000

Building Hangman - Sketching with code

Now that we've got Hyperapp installed, we're ready to try and make some steps towards our goal: Hangman.

Let's remind ourselves of our brief from Part 1:

The Computer picks a random word for us to guess
The Player inputs letters to guess the word
Like the paper version, correct letters get inserted into the word, incorrect letters get listed elsewhere
8 incorrect guesses and the Player loses
If the Player fills in the word correctly, they win.

Sketching with code

When first starting on a new problem, (that's what interface is really, a set of problems needing solution), it's important not to get too precious about how your application will end. It's important to make a start.

By "Sketching with code", we'll do the coding equivalent of a quick visual mockup of a design, let's get some things in place without being too precious about it, working in broad strokes.

We know our app() function in Hyperapp takes 3 things: init, view and node. We solved node in Part 1, so we have a choice. The State or the View?

When I'm building a website, I nearly always start with the View. Let me put my elements on the page, and then go from there. However, in this case, I'm not entirely sure how I want to take input, or how I'm going to display guesses - so let's think about State.

The Loop

In Hyperapp, we can think of our UI as a function that gets called again, and again, and again in response to outside events: user interaction, time, whatever we want.

This function takes one thing, state, which is all the information it needs to display the UI correctly. When we respond to events in the world (e.g. somebody entering a letter), we trigger an Action that changes the State.

State In, UI out. State in, UI out.

Knowing that we have this loop going on really helps us think about our State. What information do we need to be able to show the user in a game of hangman?

The word they're guessing.
The letters they've guessed.

That's it. We can get everything we need to know to display a game of hangman from these two pieces of information.

Let's sketch that in code.

Our initial state looks like this:

{
  word: 'application',
  guesses: [],
}

A word, and an array waiting to receive guesses.

We'll put that in our init, and output the word onto the screen in our view:

import {app} from 'hyperapp';
import {div, h1, h2} from '@hyperapp/html';

app({
  init: {
    word: 'application',
    guesses: [],
  },
  view: state => div({}, [
    h1({}, state.word), // we output our word from the state we passed into `init`
    h2({}, 'Your Guesses:')
  ]),
  node: document.getElementById('app'),
});

Hurray, the state we define in init becomes available to us in view. When we change state, we can change how our UI reacts to that change in view.

Making things a bit more 'Hangmany'

Seeing the word on the screen reminds me of a crucial part of Hangman's UI: you're not meant to be able to see the word you're guessing! You're also meant to display lines for letters you haven't guessed, and fill in the letters you have.

We also need to show our incorrect guesses. Phew! A fair bit to do.

Let's start by putting some guesses into our state and outputting them in our view.

import {app} from 'hyperapp';
import {div, h1, h2, ul, li} from '@hyperapp/html';

app({
  init: {
    word: 'application',
    guesses: ['a', 'b', 'c', 'd'],
  },
  view: state =>
    div({}, [
      h1({}, state.word),
      h2({}, 'Your Guesses:'),
      ul(
        {class: 'guesses'},
        state.guesses.map(guess => li({class: 'guess'}, guess)),
      ),
    ]),
  node: document.getElementById('app'),
});

We can now see our guesses on the screen, and we only really need to hide some information to have a genuine Hangman state - a good place to be in!

What the map?!

Let's quickly make sure we understand what's going on here where we display our guesses:

  state.guesses.map(guess => li({ class: 'guess' }, guess))

.map applies a function to each element in an array, and then returns that array. Because all of our UI is just functions - We're turning our array of guesses:

[
  'a',
  'b',
  'c',
  'd'
]

into an array of li functions:

[
  li({ class: 'guess' }, 'a'),
  li({ class: 'guess' }, 'b'),
  li({ class: 'guess' }, 'c'),
  li({ class: 'guess' }, 'd')
]

And of course, we know li is just a short-hand for h('li',...) - and it's h() that is adding these elements to our Virtual DOM. Remembering it's all functions will help us tidy this up later on. But for now, back to Hangman.

Hiding the answer

So, let's hide the answer, and only show our bad guesses, and we're well on our way.

To start with, our word isn't that easy to deal with is as string, so let's turn it into an array.

init: {
  word: 'application'.split(''),
  guesses: ['a', 'b', 'c', 'd'],
},

and now let's output the mdash character for each letter of the word.

(In HTML: the mdash is output with —, in Javascript we have to use a mysterious unicode ¯_(ツ)_/¯)

// import ...
// ...
const mdash = '\u2014';

// ...
app({
  //...
  view: state =>
    div({}, [
      h1({}, state.word.map(() => span({class: 'letter'}, mdash))),
      h2({}, 'Your Guesses:'),
      ul(
        {class: 'guesses'},
        state.guesses.map(guess => li({class: 'guess'}, guess)),
      ),
    ]),
  //...
});

NB: Don't forget to import the span function from @hyperapp/html here, I won't keep including that line, you'll be able to work out when to add these.

Great, we're hiding our word, but we've gone too far. We need to show the letter for letters we got right, and only show bad guesses underneath.

Time to Refactor

We want to keep moving fast, but we're duplicating a few things, and there's some definite sections to our UI: The Word and the Incorrect Guesses. Let's write some helpers and views to tidy things up.

As we need to work with arrays here, let's write a nice helper function to let us know if an array contains a thing we give it:

  const contains = (list, item) => list.indexOf(item) > -1;

This way, instead of having indexOf all over the place, we can check if a letter has been guessed like this:

contains(guesses, letter)

Or if a guess is in the word:

  contains(word, guess)

Let's put it into action.

div({}, [
  h1(
    {},
    state.word.map(letter =>
      span({class: 'letter'}, contains(state.guesses, letter) ? letter : mdash),
    ),
  ),
  h2({}, 'your guesses:'),
  ul(
    {class: 'guesses'},
    state.guesses.map(guess => li({class: 'guess'}, guess)),
  ),
]);

We can see our guesses in the word now. If the letter has been guessed, we display it, if not we show a dash.

We'll do the same for the guesses and only show the bad ones:

app({
  // ...
  view: state =>
    div({}, [
      h1(
        {},
        state.word.map(letter =>
          span(
            {class: 'letter'},
            contains(state.guesses, letter) ? letter : mdash,
          ),
        ),
      ),
      h2({}, 'Incorrect Guesses:'),
      ul(
        {class: 'guesses'},
        state.guesses
          .filter(guess => !contains(state.word, guess))
          .map(guess => li({class: 'guess'}, guess)),
      ),
    ]),
  //...
});

This time we add a filter, which only keeps the elements in an array when the filter function is true. If the word doesn't contain this guess, we output it in our bad guesses

Tidy Up Time

Ok good, we can see how hangman would work from here, we just need a way of updating the guesses, which will be our next lesson. Before then, we can do various bits of tidy up to make this look a lot easier to manage.

Putting things in drawers

I like to organize my Hyperapp applications into six drawers:

Utility Functions - general purpose functions that help us operate clearly, we wrote the contains() utility function in this part.
Helper functions - functions specific to our application that help explain our intentions for the app.
Effects (we'll use those later)
Actions (we'll use those later)
Views
The app() call

I keep these six headings in my index.js file, and use the same file for as long as possible, especially when I'm still sketching with code.

There are a couple of helpers we can write already, tidying up both of our filters.

// HELPERS
const isGuessed = (letter, state) => contains(state.guesses, letter);
const isInWord = (letter, state) => contains(state.word, letter);

// THE APP

app({
  //...
  view: state =>
    div({}, [
      h1(
        {},
        state.word.map(letter =>
          span({class: 'letter'}, isGuessed(letter, state) ? letter : mdash),
        ),
      ),
      h2({}, 'Incorrect Guesses:'),
      ul(
        {class: 'guesses'},
        state.guesses
          .filter(guess => !isInWord(guess, state))
          .map(guess => li({class: 'guess'}, guess)),
      ),
    ]),
  //...
});

This describes what we're trying to do a bit better, but we can take it further.

Remember, in Hyperapp, all views are functions. this h1 can become a function (view) called Word, and can have WordLetter views within it - moving all the detail about whether or not to display a letter or a dash somewhere else.

const WordLetter = (letter, guessed) =>
  span({class: 'letter'}, guessed ? letter : mdash);

So, first we have a WordLetter view, which is going to take a letter, and a guessed boolean, so we know whether or not show it.

Then, we want to move the whole Word into a view as well.

We need to pass state in here, because to say whether or not a letter is guessed, we need to access state.guesses (via our isGuessed helper)

Word looks like this:

const Word = state =>
  h1(
    {},
    state.word.map(letter => WordLetter(letter, isGuessed(letter, state))),
  );

and now, we can put that back into our view:

app({
  //...
  view: state =>
    div({}, [
      Word(state),
      h2({}, 'Incorrect Guesses:'),
      ul(
        {class: 'guesses'},
        state.guesses
          .filter(guess => !isInWord(guess, state))
          .map(guess => li({class: 'guess'}, guess)),
      ),
    ]),
  //...
});

Let's do something similar with the incorrect guesses, and we can move on.

// HELPERS:

// throwing `!isInWord` around was getting ugly
const badGuesses = state =>
  state.guesses.filter(guess => !isInWord(guess, state));

// ...

// VIEWS

const BadGuesses = state => [
  h2({}, 'Incorrect Guesses:'),
  ul(
    {class: 'guesses'},
    badGuesses(state).map(guess => li({class: 'guess'}, guess)),
  ),
];

// APP

app({
  init: {
    word: 'application'.split(''),
    guesses: ['a', 'b', 'c', 'd'],
  },
  view: state => div({}, [Word(state), BadGuesses(state)]),
  node: document.getElementById('app'),
});

Game Over

To finish our first sketch of hangman, we need to think about the two end states: Game Over and Victory.

Let's start with victory, we know the user has won if they have guessed all of the letters in the word before 8 tries. In other words:

const isVictorious = state =>
  state.word.every(letter => isGuessed(letter, state))

Array.every returns true if every element in the array passes the test. Our test here is whether not "every" letter "isGuessed".

We can hard code a victory and use this in our view:

app({
  init: {
    word: 'application'.split(''),
    guesses: ['a', 'p', 'l', 'i', 'c', 't', 'o', 'n'],
  },
  view: state =>
    div(
      {},
      isVictorious(state)
        ? [h1({}, 'You Won!'), Word(state)]
        : [Word(state), BadGuesses(state)],
    ),
  node: document.getElementById('app'),
});

We already have the helper we need for gameover, badGuesses. Let's just write in code somewhere how many guesses you're allowed: 7.

const MAX_BAD_GUESSES = 7; // this doesn't change, so we don't need to store it in State.


// HELPERS
const isGameOver = state => badGuesses(state).length >= MAX_BAD_GUESSES;

app({
  init: {
    word: 'application'.split(''),
    guesses: ['a', 'p', 'l', 'i', 'c', 't', 'o', 'n'],
  },
  view: state =>
    div(
      {},
      isGameOver(state)
        ? h1({}, `Game Over! The word was "${state.word.join('')}"`)
        : isVictorious(state)
        ? [h1({}, 'You Won!'), Word(state)]
        : [Word(state), BadGuesses(state)],
    ),
  node: document.getElementById('app'),
});

This gives us a working application, in theory. We just need to allow the User to interact with our application and change the guesses in the state. That's our next episode.

This tutorial was originally posted to adamdawkins.uk on 7th October 2019

Building Hangman with Hyperapp - Part 1

Adam Dawkins — Tue, 21 Jan 2020 23:25:01 +0000

Building Hangman with Hyperapp

Building interactive UIs on the modern web can be a daunting task. If you're a junior developer, making the jump from jQuery to a ‘full’ Javascript UI is massive. For seasoned developers, keeping your application architecture error free and simple is hard-work, and there are as many different best practices for React, Angular and Vue as I've had hot dinners.

Things don’t have to be this way.

Let’s build a version of Hangman in Hyperapp, and see another way user interfaces can be build in Javascript. Even if you don’t want to switch your applications over to Hyperapp, you’ll learn something that will make you a better Javascript UI developer in your existing framework of choice.

Why Hyperapp?

Putting the “Hype” into Hyperapp

Hyperapp is a Javascript framework for building user interfaces. It uses a ‘Virtual DOM’ to update the page, as you might be familiar with in other Javascript UI Frameworks, such as React, Vue, Angular, etc. The Virtual DOM is the method by which these frameworks update the page, and Hyperapp has it's own VDOM, written from the ground up for speed and size.

So what’s the difference?

For my money, Hyperapp has a few key advantages over React, Angular & Co.

It’s 1KB. That’s under 1/20th the size of React, Vue, and Angular, and a third of the size of Preact, which is a “fast 3KB alternative to React”.
A functional paradigm. Some big words here, but the way Hyperapp conceptualizes your UI and application is a delight to work with. It keeps things very simple and clear and allows you to create powerful interfaces in a way that keeps them robust and manageable in size. More on that later.
This is a bonus feature, if you like Elm, you’ll love Hyperapp. For me, Hyperapp is essentially Elm-architecture without the different language. If you don’t know what Elm is, don’t worry, you don’t need to - it's a language and framework for building front-end UIs, just like React, Vue and Angular. I've always enjoyed it for the way it conceptualies your app as a big function, but was put off of writing in a language that only compiled to Javascript - it's a learning curve for me, and anyone on my team.

Let’s dive in.

To get you started with Hyperapp, we’re going to build a version of the popular word game /Hangman/, in Hyperapp.

Our game has the following spec:

The Computer picks a random word for us to guess
The Player inputs letters to guess the word
Like the paper version, correct letters get inserted into the word, incorrect letters get listed elsewhere
8 incorrect guesses and the Player loses
If the Player fills in the word correctly, they win.

We may add to this spec as we go on, but this is the nuts and bolts of a game of hangman.

Minimum Viable Hangman

We’re going to build our Hangman game up in layers. We’ll start with something that barely counts as hitting our spec - so that we can play Hangman, and then we’ll improve and refine the user experience.

What you’ll need:

Node.js
A node package manager (either npm or yarn).
A code editor
A browser.

Installation

Let’s dive in, get hyperapp installed and get working on our game then.
Create a new folder called hyperapp-hangman, and add a Javascript and HTML file:

mkdir hyperapp-hangman
touch hyperapp-hangman/index{.js,.html}

Let’s add a package manager, you can use npm or yarn, whatever floats your boat:

cd hyperapp-hangman

npm init . -y
# OR
yarn init . -y

This allows us to add Javascript packages to our application from the inter web, so let’s go ahead and add hyperapp. After all, /that’s why we’re here!/

yarn add hyperapp@beta

npm install hyperapp@beta —save

Great, now we need some HTML.

Our HTML is really simple, we have a div#app for putting all of our UI in, and we import our Javascript file:

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
</head>
<body>
<div id="app"></div>
<script src="./index.js"></script>
</body>
</html>

To the Javascript

We're going to start by importing two things from Hyperapp. h, and app:

import {h, app} from 'hyperapp';

Let me quickly explain both.

app is a function that's going to basically 'start' Hyperapp. We're going to pass it an object in a minute, with three keys: init, view and node:

init - this is an object that describes the starting state of our application. We'll put the word we need to guess here.
view - the function we give this will take the state and return our UI. It'll end up as HTML on the page.
node - the part of the DOM we want to insert our application into, we could write that now if we wanted:

app({
init: {}, // ? - We don't know yet, maybe our guessable word
view: () => {}, // ?  - We don't know how to write views in Hyperapp yet.
node: document.getElementById('app'), // our app div in index.html
});

Views

In Hyperapp, what we're actually doing is creating virtual DOM nodes. This is a virtual representation of the UI we want to see in the browser. Hyperapp compares this virtual representation under the hood to the real DOM and makes any necessary changes.

But how do we write it? Enter h.

Updating the DOM

To explain what h does, it's worth thinking about how you'd add something to the DOM in Javascript. Let's try and add the following HTML to app using pure Javascript:

<div class="pure-javascript">
<h1>This was added with pure Javascript, check me out!</h1>
</div>

To create our div, we do this:

const div = document.createElement('div');
div.classList = 'pure-javascript';

and we append it to our #app div like so:

document.addEventListener('DOMContentLoaded', () => {
    // wait for the DOM to load
    const div = document.createElement('div');
    div.classList = 'pure-javascript';
    const app = document.getElementById('app');

    app.appendChild(div);
    });
})

Now, we need to add our <h1> to our div.

const h1 = document.createElement('h1');
h1.appendChild(
    document.createTextNode('This was added with pure Javascript, check me out!'),
    );

div.appendChild(h1);

Success! We have inserted some DOM with Javascript. This is a perfectly fine way of building a UI in Javascript, but it is ugly to work with.

To counter this, Javascript wizards invented 'hyperscript', an h function that takes the name of an element and some children.

A basic version, without attributes looks like this:

const h = (tagName, children) => {
  const element = document.createElement(tagName);

  if (typeof children === 'string') {
    element.appendChild(document.createTextNode(children));
  } else {
    children.forEach(child => {
        element.appendChild(child);
        });
  }

  return element;
};

You don't need to understand exactly what this is doing, but it allows us to use it like this:

const container = h('div', [
    h('h1', 'Hello, World!'),
    h('p', 'This is a paragraph about the app'),
]);

app.appendChild(container);

We pass our child elements in to h as an array, and textNodes in as text. Lovely.

We could extend this to include an object of attributes to add to our elements, so we could use it like this.

h('div', {class: 'pure-javascript'}, [
    h('h1', {}, 'This was added with pure Javascript, check me out!'),
]);

And there we have it.

This is actually exactly what the syntax of hyperapp's h looks like, except, under the hood, in creates a Virtual DOM rather than editting the real DOM directly.

Let's do the same thing with hyperapp:

import {h, app} from 'hyperapp';

app({
init: {}, // we don't have a state here
view: () =>
h('div', {class: 'pure-javascript'}, [
    h('h1', {}, 'This was added with pure Javascript, check me out!'),
]),
node: document.getElementbyId('app'),
});

Running Hyperapp

With our basic Javascript examples, we could just open index.html to view our code, but hyperapp is install as a node module, so we need to start things a bit differently.

The easiest way, is with Parcel JS

After installing the package, we can run parcel to start a server:

parcel index.html

Now open your browser at http://localhost:1234

Improving on `h()`

We have a couple more options available to tidy up this view:

1) @hyperapp/html

You may have noticed another pattern available to us. h('div',...) is always going to be the same for every div. We could create a div function to handle this.

const div = (attributes, children) => h('div', attributes, children);

We could do the same for h1, but it'd be time consuming.

That's what hyperapp/html has already done, We can use it to tidy up this view:

yarn add @hyperapp/html

import {app} from 'hyperapp';
import {div, h1} from '@hyperapp/html';

app({
init: {}, // we don't have a state here
view: () =>
div({class: 'pure-javascript'}, [
    h1({}, 'This was added with pure Javascript, check me out!'),
]),
node: document.getElementById('app'),
});

Our other option is to use JSX, which allows you to write your view in a way that looks like HTML. You may have seen this in React.

There is a small piece of extra configuration requried if you choose to use JSX, and your view will now look like this:

app({
init: {}, // we don't have a state here
view: () => (
    <div className="pure-javascript">
    <h1>This was added with pure Javascript, check me out!
    </div>
    ),
node: document.getElementById('app'),
});

There are some obvious benefits to JSX. If you already have written some HTML, it makes the conversion to VDOM painless. It also represents what you're actually adding to the DOM.

However, it is important to remember that underneath, both of our enhancements here are calling h() under the hood.

They're both doing:

{
view: () =>
        h('div', {class: 'pure-javascript'}, [
            h('h1', {}, 'This was added with pure Javascript, check me out!'),
        ]),
};

If you're familiar with JSX, by all means get it setup and follow along. If you're new to JS UI Frameworks, stick with h() and @hyperapp/html for this tutorial. It'll help you remember you're not writing HTML, you're writing functions that create a virtual DOM.

Now that we know a bit of what's going on, we'll get stuck into building Hangman in Part 2.

This tutorial was originally posted on adamdawkins.uk on 7th October 2019

The Hunt for the missing /: A story of anchors, location and Internet Explorer's pathname

Adam Dawkins — Wed, 05 Jun 2019 12:20:20 +0000

The nice trick with anchors and location

There’s a really nice way to get the pathname off URLs that aren’t the current window.location. If you set them as the href of an anchor element, the anchor element actually implements the same location Protocol as window.

// on https://adamdawkins.uk/articles
window.location.pathname // => “/articles”

var url = document.createElement('a');
url.href = "https://adamdawkins.uk/articles";
url.pathname; // => "/articles"

Where can this be useful? On any site where you need to manipulate or analyse URLs client-side, or, as in my case, when you’re using browser.pushState but still want to read state from a location object in the same way regardless.

On a project recently I used it like this:

//    getState :: Location -> Object
const getState = (location) => ({
    page: location.pathname,
    ...getQueryParams(location)
})

I’d call getState(window.location) on page load, but, when I changed the URL with history.pushState I needed to pass that URL into my getState function as well. Instead of trying to change the simplicity of getState (takes a location, returns an object, lovely) - we can use the fact that anchors implement the location protocol to get something we can pass to this.

 //   toLocation :: URL -> <a>
const toLocation = (url) => {
  const anchor = document.createElement('a');
  anchor.href = url;

  return anchor
}

const newURL = setQueryParams({foo: 'bar'}) // returns the whole URL, e.g. "https://adamdawkins.uk/articles?foo=bar"
const newState = getState(toLocation(newURL))

Note the the anchor DOM Element itself implements the Location protocol, not anchor.location.

Internet Explorer and relative pathnames

Lovely stuff. Enter Internet Explorer, stage right.

Internet Explorer takes relative URLs and does not treat the initial / as part of the pathname

Using our code above:

// All other browsers 
toLocation("/articles?foo=bar").pathname // => "/articles"
// Internet Explorer
toLocation("/articles?foo=bar").pathname // => "articles"

Great, thanks.

Maybe I was just unlucky, but I was matching on that / to check which page I was on:

if (state.page.match(/\/checkout/delivery\//)) {
 // …
}

And it would work, unless I pushed state in Internet Explorer, now state.page is “checkout/delivery”.

What to fix?

There’s a dilemma here. The easiest fix is to loosen my regex on the page, and not check for a preceding /, but the problem is - that is what I mean - I do want to match /checkout/delivery, and it feels wrong to change that because IE has anxiety issues about the initial /.

The fix I went for was to create a simple pathname() function that would replace the / if it had been lopped off by IE:

//    pathname :: Location -> String
const pathname = (location) =>  (
    // in IE location.pathname strips the first `/` from relative URLs, here we add it back
    location.pathname.match(/^\//) ? location.pathname : `/${location.pathname}`
)

Phew.

This article was originally published on adamdawkins.uk