Build with Wild Willows

There are more labels than these three

You have used <h1> and <p>. There are about a hundred elements and you will use perhaps fifteen of them. These are the ones that come up first.

<h1> to <h6>   headings, in order of importance
<p>             a paragraph
<ul> <li>       a list, and one item in it
<a href="...">  a link
<img src="..." alt="...">   an image
<button>        something to press
<div>           a box with no meaning of its own
<span>          a piece of text with no meaning of its own

Why the label matters, and not just the look

You could make any of these look like any other with CSS. The label is not about the look: it is what tells a screen reader that a heading is a heading, what lets a search engine understand the page, and what makes <button> respond to the keyboard without you writing a line of code.

A <div> you have made clickable does none of that. Use the element that means what you mean, and reach for <div> and <span> when nothing means it.

Attributes

The extra information inside the opening tag. href is where a link goes, src is which image to load, and alt is what the image says for anyone who cannot see it.

<a href="https://wildwillows.app">Play the game</a>
<img src="fox.jpg" alt="A red fox in long grass">

alt is not optional and it is not a caption. It is the sentence a blind reader hears in place of the picture, and it is also what shows up if the image fails to load on school wifi.

Formatting text

Half of this belongs to CSS and half to JavaScript, and the rule for choosing is worth stating: if it is about appearance, use CSS. Uppercasing a heading in CSS leaves the real words in the HTML, so search, screen readers and copy-and-paste all still get what you actually wrote.

/* CSS: how it looks */
text-transform: uppercase;    /* the underlying text is unchanged */
letter-spacing: 0.08em;       /* small caps and labels need this */
text-align: center;
font-variant-numeric: tabular-nums;   /* digits line up in a column */
white-space: nowrap;          /* stop this one from wrapping */

/* JavaScript: what the text IS */
name.toUpperCase();
name.trim();                  /* strip stray spaces from input */
name.split(" ");              /* "Red Fox" -> ["Red", "Fox"] */
list.join(", ");              /* back the other way */

The tabular-nums one is a real fix, not a nicety. In most fonts a 1 is narrower than a 7, so a column of numbers looks ragged until you ask for the fixed-width digits the font already contains.

One value, used in ten places

A custom property is a name you invent, set once, and use anywhere below it. Change the value at the top and every use of it follows, which is how a whole site changes color in one line.

:root {
  --green: #4a7c59;
  --ink: #3b4232;
  --radius: 14px;
}

.card   { border: 2px solid var(--green); border-radius: var(--radius); }
.btn    { background: var(--green); }
h1, h2  { color: var(--ink); }

Dark mode on this page is exactly this and nothing else: the same rules throughout, with about twenty of these values pointed somewhere darker when you press the moon.

The same page on a phone

A @media block applies its rules only when the condition holds. Write the phone layout first and add the wider one on top, because a narrow single column is the thing that always works.

.layout { display: grid; gap: 16px; }          /* one column, always */

@media (min-width: 700px) {
  .layout { grid-template-columns: 1fr 2fr; }  /* two, when there is room */
}

Transitions: from one state to the other

The hover above used a transition. The property is more general than that: name what should animate, how long it should take, and how it should ease.

.a { transition: background 0.3s ease; }
.box:hover { background: #d8eec2; }

transition: all 0.3s works and is a bad habit: it animates properties you did not mean, including ones that force the browser to redo the whole layout. Name what you want.

transform: move it without moving anything else

transform shifts, scales or rotates an element for display only. Everything around it stays exactly where it was, which is why a button can grow on hover without shoving the rest of the row sideways.

.lift:hover { transform: translateY(-4px); }
.grow:hover { transform: scale(1.12); }

Animating transform and opacity is cheap, because the browser can do it without recalculating where anything is. Animating width, height, top or margin makes it redo the layout on every frame, which is what a janky page usually is.

Keyframes: an animation that runs on its own

A transition needs something to change. When you want motion that just happens, describe the stages with @keyframes and attach them with animation.

@keyframes rise {
  from { opacity: 0; transform: translateY(10px); }
  to   { opacity: 1; transform: translateY(0); }
}
.card { animation: rise 0.45s ease both; }

The pulse is the honest use of animation: it says the page is working rather than broken. Chapter 5 fetches real data over a real network, and on school wifi that wait is long enough to need saying something about.

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

This page does it too. The arrow that turned when you opened this panel, and the diagram in chapter 9 that lights up one step at a time, both check that setting first and stop moving if it is on.

The page is a tree, and that is why querySelector works

When the browser reads your HTML it builds a tree in memory called the DOM. Your <li> elements are inside a <ul>, which is inside <body>, which is inside <html>.

document.querySelector("#animal-count") searches that tree, and changing an element changes the tree. The page you see is a drawing of it, which is why the text changed without anything reloading.

const el = document.querySelector("#animal-count");
el.parentElement;        /* upwards */
el.children;             /* downwards */
el.closest("section");   /* upwards, to the first match */
document.querySelectorAll("li");   /* every match, not just the first */

textContent and innerHTML

textContent puts text on the page and never runs it. innerHTML parses what you give it as HTML, which is powerful and is why chapter 9 has a warning attached to it.

el.textContent = "<b>hello</b>";   /* shows the angle brackets */
el.innerHTML   = "<b>hello</b>";   /* shows hello, in bold */

Where a name lives

The three words are compared at the top of this chapter. The part left over is scope: not whether a name can be repointed, but which lines of the file can see it at all.

That last row is the reason var is left alone now. A name declared inside an if block with var is still there after the block ends, and still there at the bottom of the function, which makes it possible to use a name you thought you had finished with and get no complaint from anyone.

function check(animal) {
  if (animal.rarity === "rare") {
    var note = "worth seeing";
  }
  return note;   /* var: reachable here, and undefined if the if never ran */
}                /* const or let: an error, which is the more useful answer */

A name that stops existing at the closing brace is a name you cannot accidentally read afterwards. That is the whole argument, and it is why the two newer words behave the same way as each other and differently from the old one.

JSON is text

The response you just looked at arrived as a string of characters. Turning that text into real JavaScript objects and arrays is a separate step, and it is the only reason data.animals[0].name works at all.

const text = '{"name": "Red Fox", "rarity": "rare"}';

const animal = JSON.parse(text);    /* text   -> object */
animal.name;                        /* "Red Fox" */

JSON.stringify(animal);             /* object -> text, to send or store */

Chapter 5 calls response.json(), which does the fetching and the parsing in one move. This is what it is doing underneath.

It looks like JavaScript and it is not

JSON is deliberately smaller than JavaScript, because it has to be readable by programs written in any language. The rules it does not share:

• keys must be in double quotes: "name", never name or 'name'
• no comments
• no trailing comma after the last item
• no functions, no undefined, no dates: only strings, numbers, booleans, null, arrays and objects

Those are the six types from the table above, and that is not a coincidence. The type list is the format.

Where the data actually comes from

/GameData is one address that hands back everything. Many APIs instead give you an address per thing, and ask you to say which one you want:

/GameData                     everything, in one response
/Animals/red-fox               one animal        (a common alternative)
/Animals?biome=meadow          a filtered list   (a query string)

One big response is simpler to learn against and simpler to cache, which is why this one is built that way. Once you are choosing for yourself, the question is whether the page needs most of the data or a little of it.

What the API told you besides the data

The probe in chapter 4 reported a status of 200. Every HTTP response carries one, and the first digit is the whole summary.

A 404 is not an error, and this catches people out

fetch only rejects when the request could not be made at all: no network, no such host, blocked. A 404 is a request that succeeded and came back with bad news, so it lands in your then, not your catch. That is what response.ok is for.

const response = await fetch(url);

if (!response.ok) {
  message.textContent = "Could not load the game data.";
  return;
}

const data = await response.json();

Without that check, a 404 returns an HTML error page, .json() tries to parse it, and the message a student gets is Unexpected token '<'. That error is in the runner's list on this page, and this is where it comes from.

Waiting is not stopping

JavaScript runs one thing at a time. When you await a fetch, your function is set aside and the browser goes back to handling clicks, scrolling and drawing. When the response arrives, your function is put back in the queue and picks up where it left off.

That is why a slow API does not freeze the page, and why a long for loop does: the loop never lets go.

console.log("first");
setTimeout(() => console.log("third"), 0);   /* queued, even at zero delay */
console.log("second");

Zero milliseconds still means "after the current work finishes". The queue is the point, not the delay.

Object.keys(), .values() and .entries()

You reached into the data by naming the parts you wanted. This is how you read an object whose field names you do not already know.

Object.keys(animal);
Object.entries(animal.requirements);   /* [["minHealth", 35], ...] */

This is how the collapsible tree above is built. It has never seen the Wild Willows data: it asks every object what its keys are and draws whatever it finds.

Recursion, which this page is already doing

The tree cannot know how deep the data goes. An animal contains requirements, which contains objects, which could contain anything. So it does not try. It handles one value, and if that value has parts inside it, it calls itself on each one.

function countAll(value) {
  if (value === null || typeof value !== "object") return 1;
  return Object.values(value).reduce((total, part) => total + countAll(part), 0);
}

Two parts, always. A base case that answers without calling itself (a plain value counts as one), and a step that makes the problem smaller. Leave out the base case and it calls itself until the browser stops it, which is the error Maximum call stack size exceeded.

Everything is either truthy or falsy

An if does not need a comparison. Give it any value at all and JavaScript decides whether that value counts as yes. Six things count as no, and everything else counts as yes.

/* the falsy six */
false   0   ""   null   undefined   NaN

/* so this works, and reads well */
if (matches.length) { ... }        /* any number but 0 */
if (animal.fact) { ... }           /* any string but "" */

?. and ??

Reading through something that might not be there throws Cannot read properties of undefined. The optional dot stops at the gap instead.

animal.requirements.water.tiles      /* throws if there is no water */
animal.requirements.water?.tiles     /* undefined if there is no water */

/* and a default for when it IS missing */
const tiles = animal.requirements.water?.tiles ?? 0;

?? only steps in for null and undefined, which is what makes it different from ||. With ||, a real 0 would be replaced by the default, because zero is falsy.

Many outcomes: switch

A long else if chain comparing one value against a list is what switch is for. It is not more powerful, it is easier to read.

switch (animal.rarity) {
  case "rare":
    label = "Rare find";
    break;
  case "uncommon":
    label = "Uncommon";
    break;
  default:
    label = "Common";
}

The break is not optional. Without it execution falls through into the next case and keeps going, which is occasionally useful and much more often a bug.

.some() and .every()

.filter() hands back a list. Sometimes you only want a yes or a no about the whole list, and these give you one straight away.

meadow.some(animal => animal.rarity === "rare");    /* true */
meadow.every(animal => animal.rarity === "rare");   /* false */

Same question you gave .filter(). Different shape of answer: a boolean instead of an array.

new Set(), for the values you did not know were there

This chapter listed the real values of biome, rarity, kind and trophic so your filters would match something. Here is how that list was made, rather than looked up.

const distinct = [...new Set(data.animals.map(a => a.trophic))].sort();

Change trophic to any other field and you have asked the data a question nobody wrote down the answer to. That is most of what data work actually is.

Three more, briefly

.includes() asks whether a value is in a list. .slice() takes a section out without changing the original. .indexOf() says where something is, or -1 if it is not there at all.

fox.eats.includes("prairie-vole");   /* true */
data.animals.slice(0, 5);            /* the first five */
data.animals.slice(-3);              /* the last three */
distinct.indexOf("herbivore");       /* a position, or -1 */

The -1 is worth remembering. It is the same idea as the undefined in chapter 6: a real answer meaning "not here", which will quietly behave like a number if you forget to check it.

A function is a value

You have been handing functions to other functions throughout this chapter without anyone saying so out loud. That is the trick that makes .filter() possible: a function can be stored in a variable and passed around exactly like a number or a string.

const isRare = animal => animal.rarity === "rare";
data.animals.filter(isRare);

Naming the question is often clearer than writing it inline, and you can reuse it in a .some(), an .every() and a .find() without repeating yourself.

Changing something, versus copying it

This chapter copied the array with [...] before sorting it. Here is what that actually means, and why it is the kind of bug that takes an afternoon to find.

const sorted = original.sort();  /* `original` is now sorted too */

Methods that build something new (.map, .filter, .slice) are safe to use anywhere. Methods that rearrange in place (.sort, .reverse, .push) change something somebody else might still be holding.

How long does this take?

.filter() over 150 animals looks at all 150. That is instant, so it never comes up. Over 150 million rows it would look at 150 million, and the same line of code would take minutes.

The useful idea is not the speed, it is the shape: the work grows in step with the data. Chaining .filter().sort().map() walks the list three times, which is still that same shape. But a filter nested inside a filter checks every animal against every animal, which is 150 times 150, and at a million rows that is a trillion comparisons and a page that never loads.

/* one pass per method: fine at any size you will meet */
data.animals.filter(isRare).sort(byName).map(toName);

/* every animal against every animal: 150 x 150 here, and it does not scale */
data.animals.filter(a => data.animals.some(b => b.biome === a.biome));

Computer scientists write these as O(n) and O(n squared) and call it big-O notation. The notation is a name for the question you can now ask, which is: if the data got a thousand times bigger, what happens to this line?

Formatting a number so a person can read it

Putting a number on a page is a different job from calculating one. 0.3333333333333333 and 1250000 are both correct and neither is readable. The browser will format them for you, in the reader's own language and conventions.

share.toFixed(1);
(1250000).toLocaleString("en-US");
new Intl.NumberFormat("en-US", { style: "percent" }).format(share);

.toFixed() hands back a string, not a number, which matters the moment you try to sort by it. Round for display, keep the real number for the arithmetic.

Building the list without innerHTML

The warning above is real, and this is the other way to do it. It is longer, and it cannot run anything it is given, because at no point is there any HTML to parse.

const list = document.querySelector("#animal-list");

for (const animal of data.animals) {
  const item = document.createElement("li");
  item.textContent = animal.name;   /* text, never markup */
  list.appendChild(item);
}

Use innerHTML with data you trust, which is what you have here. Use this the moment any part of the text came from a person: a search box, a comment, a name someone typed.

Emptying it first

Run your render twice and you get the list twice. innerHTML = items happens to replace, but appendChild adds, so anything that can re-render needs to start from empty.

list.innerHTML = "";   /* then build it */

This is the bug behind "why do I have fifty animals" in every project that adds a filter button later.

The reference professionals actually use

MDN Web Docs is free, accurate and written by the people who build browsers. Search for any method or property on this page plus “mdn” and the first result will be the real documentation. It assumes you already know some of it, and reading it anyway is most of how the rest gets learned. The rest of the places worth looking, and what to do about code you did not write, are at the top of this page.

Three things worth building next

• A search box: an <input>, an input event listener, and the .filter() from chapter 8 run against whatever they typed.
• A picker: buttons for the six biomes, each one re-running your render with a different value.
• A comparison: two animals side by side, built from the same data with the same code twice.

All three are the code you already have, with one thing that changes. That is what most of web development turns out to be.

When you get stuck

Read the error panel first: it names the line and often the mistake. Then console.log the value just before the line that broke. The error marks where things stopped working, not where they went wrong, and those are usually a step apart.

The Code Builder has the same editor, the same error explanations and thirty project ideas to pick from. Your code from this chapter comes with you.