Forem: Craft Code

Data-driven UIs

Charles F. Munat — Wed, 01 May 2024 01:37:44 +0000

DDUIs mean a single source of truth and the benefits that come with it.

Building on a previous article, DOM to JSON and back, we now move on to data-driven UIs.

A data-driven UI is a user interface generated dynamically from a query response. In short, the database schema determines the interface to that data.

This gives us a single source of truth. Our interface (e.g., forms) cannot get out of synch with our data source. If we update the database, then the interface updates itself instantly.

Key takeaway

Here is how things are usually done: we build a database with a schema.

Then we build an API that sits in front of it. Then we build an interface to that API. All hard-coded.

Have fun keeping them in synch.

What we propose here is to extend the database schema. We add enough information to it to allow us to generate the API and UI dynamically. Then we generate them on the fly.

This means we have one source of truth. When that source changes, the interface updates itself instantly to match it.

We call this a data-driven UI. It rocks.

Start at the finish

To determine what we need to add to our database schema and query response, letʼs start with the interface. Thatʼs where the rubber meets the road, right? Weʼll keep it simple.

How about a form used to update a userʼs profile? Something like this:

<form action="#" id="edit-profile" method="POST">
  <input type="hidden" name="_charset_">
  <input type="hidden" name="id" value="255c08b2-6606-424b-a339-d3f9ebe50a21">
  <div class="text-field">
    <label for="name">Name</label>
    <input id="name" name="name" required type="text">
  </div>
  <div class="email-field">
    <label for="email">Email address</label>
    <input id="email" name="email" required type="email">
  </div>
  <div class="boolean-field">
    <label for="display-name-on-profile">
      <input
        id="display-name-on-profile"
        name="displayNameOnProfile"
        type="checkbox"
        value="true"
      >
      Display email on profile
    </label>
  </div>
  <fieldset class="member-picker">
    <legend>Favorite color</legend>
    <label for="gray">
      <input
        checked
        id="gray"
        name="favoriteColor"
        type="radio"
        value="#999"
      >
      gray
    </label>
    <label for="red">
      <input
        id="red"
        name="favoriteColor"
        type="radio"
        value="#f00"
      >
      red
    </label>
    <label for="green">
      <input
        id="green"
        name="favoriteColor"
        type="radio"
        value="#0f0"
      >
      green
    </label>
    <label for="blue">
      <input
        id="blue"
        name="favoriteColor"
        type="radio"
        value="#00f"
      >
      blue
    </label>
  </fieldset>
  <div class="button-bar">
    <button type="submit">Save changes</button>
  </div>
</form>

What did we need to know to code this form?

First, we need to know what data it will include and the datatype of each:

The userʼs ID, which is of type UUID.
The userʼs name, which is a character string. This might have some limitations, such as characters allowed or limits on length.
The userʼs email address, which is of type EmailAddress. This type does not yet exist, so we will create it.
A boolean flag to decide whether to display the userʼs email address on their profile or leave it off.

Now letʼs consider what else we need to know.

ID

We know that the user cannot update their ID, so this is readonly. Should the user see this? It would only add to the clutter. So letʼs make it hidden.

We donʼt care what type the ID is because we are going to return it unchanged. That said, we know that it is a UUID.

From the above, we can see that the proper widget for the ID is an input of type hidden. We can treat the UUID as a string.

Name

We know that the user can update their name, so this field is mutable. And visible. And itʼs a string.

A short string, so that means an input of type text rather than a textarea.

Email address

We also know that the user can update their email address. And verify it by clicking on a link in an email sent to that address. It should be mutable and visible and of type EmailAddress, hence an EmailField.

That gives us a semantic advantage. The browser can do validation for us. Or we can add our own, but use the browserʼs validation as a fall back.

We also need to set the name and email address to required.

Display name on profile

This field requires a simple yes or no. Does the user want to display their email address on their profile?

The type, then, is boolean, and the best way to collect this data point is an input of type checkbox.

If we do this correctly in the database, then the type is a BOOLEAN type. So the value is either TRUE or FALSE. We can build our component so that it works with this type.

Does it matter that the specific widget is a checkbox? No. So we call this widget a BooleanField.

One important distinction of a DDUI is that it is schema-centric. We donʼt care what widget we use. Thatʼs up to the interface. We care about the datatype.

That is why we call this a BooleanField instead of a “CheckboxField“. It may seem trivial, but precise language is very important. It helps to re-orient oneʼs brain toward a DDUI approach.

Favorite color

Now we are asking the user to make a choice from a set of options. The key word here is set. In short, we are asking the user to choose one member from that set.

The widget for this is then a MemberPicker because it permits one to choose a single member from a set. If we were allowing multiple selections, then weʼd have a SubsetPicker (or Chooser or whatever).

Items in a set are also called elements. But “ElementPicker“ might be confusing as we are also working with HTML elements.

In this instance, our set has four members, each with a label and a value:

gray: #999
red: #f00
green: #0f0
blue: #00f

Besides the favoriteColor, we will need this full set of color options. The back end will have to provide these, but theyʼd be in the HTML anyway.

What widget should we choose? Well, we have options. We could use a select element. But for only four choices, it would be nice to see all at once. That means inputs of type radio.

But see below.

The “Save changes” button

We need some way to trigger the action that saves our changes. There are several possibilities, but easiest is to wrap our inputs in a form. And add a submit button.

And here comes Roy Fielding's “Hypertext As The Engine Of Application State”: HATEAOS. Our server needs to tell us which actions are available for Profile.

When we load our example profile page, the user agent (browser) makes an HTTP request to the server. The server sends an HTML document. This links to various other documents: images, stylesheets, scripts, etc.

In our scenario, this page then does an AJAX request to retrieve the data.

On most pages, the HTML form is already in place. We use JavaScript to enter into the form using JavaScript. But in our case, with a DDUI app, the form does not exist until the AJAX requests returns. Then JavaScript both builds the form and fills it with the data.

As the form is not hard coded, we donʼt know where to submit it. What is the formʼs action? Is it a GET or a POST? So we need this metadata in our AJAX response.

This has the added benefit of making the API discoverable.

Putting it all together

So here is a first pass at our current schema:

{
  "type": "Profile",
  "properties": [
    {
      "name": "id",
      "type": "uuid",
      "readonly": true,
      "hidden": true
    },
    {
      "name": "name",
      "type": "string",
      "required": true
    },
    {
      "name": "email",
      "type": "EmailAddress",
      "required": true
    },
    {
      "name": "displayNameOnProfile",
      "type": "boolean",
      "default": true
    },
    {
      "name": "favoriteColor",
      "type": "Member",
      "default": "gray",
      "options": [
        {
          "label": "gray",
          "value": "#999"
        },
        {
          "label": "red",
          "value": "#f00"
        },
        {
          "label": "green",
          "value": "#0f0"
        },
        {
          "label": "blue",
          "value": "#00f"
        },
      ]
    }
  ]
}

Easy peasy, right?

Our ID is not visible, so we know to use a hidden field for it. So:

Name is a StringField. We use an input of type text.
Email is an EmailField. This uses an email input.
“displayNameOnProfile” is a BooleanField: an input of type checkbox.
And “favoriteColor” is a MemberPicker. In this instance, a set of inputs of type radio.

We get all this from the query response and the schema. We no longer need to hard code the form.

We also know to:

Default displayNameOnProfile to checked (true)
Set our default favoriteColor to gray

And we know that the whole thing is the Profile type.

We could return this schema parallel to the query response containing our values. But why not insert the current values and return them with our schema?

Our Profile schema with current values:

{
  "type": "Profile",
  "properties": [
    {
      "name": "id",
      "type": "uuid",
      "readonly": true,
      "hidden": true,
      "value": "255c08b2-6606-424b-a339-d3f9ebe50a21"
    },
    {
      "name": "name",
      "type": "string",
      "required": true,
      "value": "Bob Dobbs"
    },
    {
      "name": "email",
      "type": "EmailAddress",
      "required": true,
      "value": "bob@dobbs.guru",
      "verified": true
    },
    {
      "name": "displayNameOnProfile",
      "type": "boolean",
      "default": true,
      "value": false,
    },
    {
      "name": "favoriteColor",
      "type": "Member",
      "default": "gray",
      "options": [
        {
          "label": "gray",
          "value": "#999"
        },
        {
          "label": "red",
          "value": "#f00"
        },
        {
          "label": "green",
          "value": "#0f0"
        },
        {
          "label": "blue",
          "value": "#00f"
        },
      ],
      "value": "blue"
    }
  ]
}

OK, now what can we do with this?

Adding HATEOAS

As mentioned above, we need to include a set of available actions. For our Profile, these are CRUDL: create, retrieve, update, delete, and list. Letʼs put them in an actions property and add them to our Profile schema:

{
  "actions": {
    "create": {
      "method": "PUT",
      "url": "/profiles/{id}"
    },
    "retrieve": {
      "method": "GET",
      "url": "/profiles/{id}"
    },
    "update": {
      "method": "PATCH",
      "url": "/profiles/{id}"
    },
    "delete": {
      "method": "DELETE",
      "url": "/profiles/{id}"
    },
    "list": {
      "method": "GET",
      "url": "/profiles"
    }
  }
}

Of course, we may not permit all these actions all the time. We have to consider authorization as well. But then we simply leave them off the actions list.

There is much more that we can do with this! For example, we can un-camelCase the name property to get the field label. Better, letʼs default to that, but use a label property to override the name where needed.

We can also add more data to our actions. For example, a label for the button (defaulting to “create”, etc.). Or a description of what the action does. Or limits on the action, such as a Duration that disables it except during that duration. (Or the reverse.)

The possibilities are endless.

Oh, the benefits!

The most important benefit of a DDUI is the one mentioned at the top of this essay: a single source of truth. But there is so much more.

This approach requires much less effort. Devs donʼt hard code the same set of components over and over again. Instead, they maintain the jsonToDom mapping. Once we build this renderer, we need only to add occasional new options.

Your database schema then represents two things:

Your domain
Metadata to help configure the interface

Your database already knows the datatype of everything you persist. Why not clue in the front end? We can also include metadata to permit us to configure the front end.

For example: we used radio buttons for our MemberPicker. But what if there are fifty options? Then weʼd likely want a select element instead. Or some kind of “typeahead” widget. Our MemberPicker widget will output any of these, but how does it know which one to use?

One way is to set the type of widget in the query response, but thatʼs a bad idea. The schema should have no knowledge or interest in how we present these data.

For one to seven options, use radio buttons.
For eight to thirty-two options, use a select element.
For thirty-three or more options, use a lookahead field.

We could hard code this into the widget, but why not load a configuration when the app starts up?

We can also run this on the server side if we prefer. Or generate partial HTML to create a static site and then do the rest on the client side. Kind of how React used to work.

Now, when we need to change the interface, we donʼt have to create the race condition we usually get. Thatʼs where the back and and front end devs block each other.

We also donʼt have to make changes in three different places. With the virtual certainty that they will get out of synch and create problems. Instead, we update the database once and presto! The front end updates itself instantly.

Here is our final simple DDUI schema for Profile:

{
  "type": "Profile",
  "properties": [
    {
      "hidden": true,
      "name": "id",
      "readonly": true,
      "type": "uuid",
      "value": "255c08b2-6606-424b-a339-d3f9ebe50a21"
    },
    {
      "name": "name",
      "required": true,
      "type": "string",
      "value": "Bob Dobbs"
    },
    {
      "label": "Email address",
      "name": "email",
      "required": true,
      "type": "EmailAddress",
      "value": "bob@dobbs.guru",
      "verified": true
    },
    {
      "default": true,
      "name": "displayNameOnProfile",
      "type": "boolean",
      "value": true,
    },
    {
      "default": "gray",
      "name": "favoriteColor",
      "options": [
        {
          "label": "gray",
          "value": "#999"
        },
        {
          "label": "red",
          "value": "#f00"
        },
        {
          "label": "green",
          "value": "#0f0"
        },
        {
          "label": "blue",
          "value": "#00f"
        },
      ],
      "type": "Member",
      "value": "blue"
    }
  ],
  "actions": {
    "create": {
      "method": "PUT",
      "url": "/profiles/{id}"
    },
    "retrieve": {
      "method": "GET",
      "url": "/profiles/{id}"
    },
    "update": {
      "method": "PATCH",
      "url": "/profiles/{id}"
    },
    "delete": {
      "method": "DELETE",
      "url": "/profiles/{id}"
    },
    "list": {
      "method": "GET",
      "url": "/profiles"
    }
  }
}

The above JSON, when run through our renderer function, will generate the HTML below. This is an update form.

<form
  action="/profiles/255c08b2-6606-424b-a339-d3f9ebe50a21"
  data-method="PATCH"
  id="edit-profile"
  method="POST"
>
  <input type="hidden" name="_charset_">
  <input
    type="hidden"
    name="id"
    value="255c08b2-6606-424b-a339-d3f9ebe50a21"
  >
  <div class="text-field">
    <label for="name">Name</label>
    <input
      id="name"
      name="name"
      required
      type="text"
      value="Bob"
    >
  </div>
  <div class="email-field">
    <label for="email">Email address</label>
    <input
      id="email"
      name="email"
      required
      type="email"
      value="bob@dobbs.com"
    >
  </div>
  <div class="boolean-field">
    <label for="display-name-on-profile">
      <input
        checked
        id="display-name-on-profile"
        name="displayNameOnProfile"
        type="checkbox"
        value="true"
      >
      Display email on profile
    </label>
  </div>
  <fieldset class="member-picker">
    <legend>Favorite color</legend>
    <label for="gray">
      <input
        id="gray"
        name="favoriteColor"
        type="radio"
        value="#999"
      >
      gray
    </label>
    <label for="red">
      <input
        id="red"
         name="favoriteColor"
        type="radio"
        value="#f00"
      >
      red
    </label>
    <label for="green">
      <input
        id="green"
        name="favoriteColor"
        type="radio"
        value="#0f0"
      >
      green
    </label>
    <label for="blue">
      <input
        checked
        id="blue"
        name="favoriteColor"
        type="radio"
        value="#00f"
      >
      blue
    </label>
  </fieldset>
  <div class="button-bar">
    <button type="submit">Save changes</button>
  </div>
</form>

Whatʼs next?

Look for more detailed articles on this topic in the future. With plenty of code examples. Even some npm (or JSR) libraries.

But the most exciting part of this is the core of the whole system: the database. We need a database that will permit us to provide infinite detail about our schema. And keep the schema strict. And permit us to update it on-the-fly whenever we want to.

And we know just the right type of database for this purpose.

More soon.

The proximity principle

Charles F. Munat — Thu, 29 Feb 2024 23:16:39 +0000

Design principles make for better DX and better code.

8 minutes or so, 2056 words, 5th grade

Do you want to write high-performing code quickly, without bugs or tech debt? We hope thatʼs a rhetorical question.

If your answer is yes, then here is the trick: reduce cognitive load.

The more you do to keep cognitive load to a minimum, the better your code will be. The greater the cognitive load, the harder it will be to understand and reason about your code.

Key takeaway

There are plenty of arguments about the right way to code web applications.

Some argue for strict “separation of concerns”. Others want to work with a single language. They prefer to generate their HTML and CSS programatically.

We beg to differ. We insist that the key to great code is to minimize cognitive footprint.

One way to do this is to apply the proximity principle from design thinking to our code. When we do so, it becomes clear how separating HTML, CSS, and JavaScript works to reduce cognitive load.

The proximity principle explained

The proximity principle instructs us to group similar items together. And to separate dissimilar items. Generally, we do this with whitespace, but we can also break code into separate files.

You can see this in the design of interfaces:

As you can see above, A, B, and C are quite similar. Because we have grouped them together, a viewer will immediately grasp this relationship.

X, Y, and Z are somewhat less similar, but still related. But not to A, B, and C. The clear grouping and separation makes this obvious.

The circle 0 appears unique.

But what happens if we ignore the proximity principle? Nothing good:

This same principle applies to code. Why wouldnʼt it? The truth is that all the design principles apply to written code as well. Design is design and everything has a design. But is that design arbitrary and accidental? Or thoughtfull and deliberate?

Applying the proximity principle to code

We can apply the proximity principle to our code. Most of us already do.

The first level of proximity, or better, use of whitespace, is within each line of code.

Withoutwhitespacecognitiveloadgoesupdramatically.

How much longer did it take you to parse that sentence? Without spaces you have to make an effort to find the individual words. Our guess is that the cognitive load increased by at least an order of magnitude. Thatʼs ten times!

The letters that make up a word have a stronger relationship to each other than to the letters in an adjacent word. So we group the letters of each word and put a space between them and the next word.

Thus, it is difficult to understand why some coders prefer num=777 to num = 777. There are three different objects here. The first is a variable name, num. The second is the assignment operator, =. The last is a number, 777.

The whitespace makes clear that they serve different purposes. Placing them on the same line and away from other similar code makes clear that they have a relationship. Namely, that they are parts of a single statement.

It is no different in prose. We group words into phrases. We group phrases into sentences. We group sentences into paragraphs and paragraphs into larger blocks, such as sections.

These groups should not be capricious. If we move punctuation arbitrarily, clarity suffers. And although many people appear to have abandoned the idea of a paragraph as a container for a single thought, that remains a better way.

It astonishes us how many programmers argue that this is all a matter of personal style or opinion. It is not. The difference in cognitive load is measurable. What gain offsets this loss of clarity? The argument for reducing file size ended long ago.

We can also group items using blank lines. This, too, is widely ignored. Weʼre not sure what the benefit is. Failure to use the proximity principle makes for difficult code.

Why write code like this:

function getOrdinal(cardinalNumber = 0): string {
  const onesDigit = cardinalNumber % 10
  if (onesDigit === 1) { return `${cardinalNumber}st` }
  if (onesDigit === 2) { return `${cardinalNumber}nd` }
  if (onesDigit === 3) { return `${cardinalNumber}rd` }
  return `${cardinalNumber}th`
}

When we can write it like this:

function getOrdinal(cardinalNumber = 0): string {
  const onesDigit = cardinalNumber % 10

  if (onesDigit === 1) {
    return `${cardinalNumber}st`
  }

  if (onesDigit === 2) {
    return `${cardinalNumber}nd`
  }

  if (onesDigit === 3) {
    return `${cardinalNumber}rd`
  }

  return `${cardinalNumber}th`
}

Good use of whitespace makes code easy to read and understand.

Granted, weʼve taken our compressed example to an extreme. Few would write code quite that compressed. But the point is that we already apply design principles to our code to make it much more readable. And that makes a big difference.

In a similar way, we use syntax highlighting for contrast and to show functional relationships. Who shuns syntax highlighting? We use it to make clear instantly the function of each bit of code: This is a number. This is a string. This is a keyword. This is an operator.

Way back in 1995, Robin Williams (not that one) wrote a book on design principles for developers. We at Craft Code have been applying its principles ever since.

She suggested the acronym “CRAP” as an easy way to remember four key design principles. These are Contrast, Repetition, Alignment, and Proximity. Misuse them and what do you get? Crap.

How much better to use all the design principles in our code! How is code really any different from prose?

Forget separation of concerns

Think proximity.

Browsers understand three types of code: HTML, CSS, and JavaScript. Weʼll leave WASM for another day.

We can send HTML, CSS, and JavaScript to the browser. Or we can send the bare minimum to load a script and then use JavaScript to manipulate the DOM directly.

There are times when the latter approach makes sense. But most of the time, it fails the proximity principle. HTML, CSS, and JavaScript serve different functions. As they are doing different things, it makes sense to group them and move them away from each other.

Skip the next two sections if this is all review to you.

HyperText Markup Language (HTML)

HTML is the first language of the World Wide Web. Tim Berners-Lee created it to mark up physics documents for sharing. He based it on SGML, the Standard Generalized Markup Language. The goal of SGML is to make documents machine-readable.

HTML is all about content. We want to organize that content into a set of nested “boxes”. We do that by marking the start and finish of each box with sets of angle brackets we call “tags”. To make clear where a box ends, we include a slash in the closing tag: <>content</>.

But we also want to say whatʼs in the box. To do this, we apply a label to the contents. And to be extra clear, we add this label to both the opening and closing tags: <em>emphasized</em>. Now our box has meaning.

We can also provide more information about what is in the “box”. We call this information metadata and we add it using attributes as key-value pairs. We add the attributes only to the opening HTML tag. For example: <a href="https://craft-code.dev/">Craft Code</a>.

We also allow some empty elements and a few empty attributes.

With good use of “CRAP”, we can make our HTML easy to read. We use a monospace font to ensure alignment. Then we use indentation to show nesting. This makes our code comprehensible at a glance.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta
      content="width=device-width, initial-scale=1"
      name="viewport"
    />

    <title>This is a title</title>
  </head>
  <body>
    <main>
      <h1>Consectetur adipiscing elit</h1>

      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent in mauris tempus <strong>diam imperdiet gravida</strong> ut non diam. Maecenas in malesuada velit, ut porttitor libero. Proin vitae condimentum metus.</p>
    </main>
  </body>
</html>

Machine readable and easily understood by humans.

Note the use of blank lines to group content by function.

If we deliver the above code to a browser, it will display our content. We have not provided any directions for how to style it. But the browser makers will still want to reduce cognitive load for the users.

So the browser will apply a default stylesheet to the content.

The browser will display the h1 element in a larger font and on its own line. It will add a new line after the p (paragraph) element. But it will bold the contents of the strong element and let it flow inline.

The default stylesheet does all this. It helps to make plain HTML content responsive and accessible.

The most common mistake made by those new to HTML is to confuse the default stylesheet with the HTML itself. This is an error. The p element does not have a style. Neither does the h1 element.

It is the default stylesheet that has the styles.

The p element has a meaning. It represents a set of one or more sentences that express a single idea or theme.

The h1 element also has a meaning. It represents the top-level heading (title) for a document or article. There is typically only one per web page.

We call this association of meaning with HTML elements “semantics”. Thus, semantic HTML.

The earliest versions of HTML included elements intended to control presentation. This was before CSS. Those elements (e.g., font) are obsolete now. Later versions of HTML abandoned them in favor of keeping the styling separate. Wise move.

Cascading Style Sheets (CSS)

Cascading Style Sheets came along less than a decade into the World Wide Web. By the turn of the millennium, they were in widespread use.

That said, standardizing CSS across browsers took quite a bit longer. As did fixing some poor choices. But now pretty much every web site or app uses CSS to control presentation.

As HTML is for marking up content, CSS is for styling HTML. CSS uses selectors to grab the HTML element (or elements) that it wants. Then it applies a set of style properties to that element.

This is easier in theory than in practice. Achieving mastery in CSS is no mean feat — as any good front-end developer will tell you.

But we can make CSS much more comprehensible! Highlight the syntax and use the proximity principle, as below. You can almost feel the cognitive load melting away.

Here is some poorly-formatted CSS:

figure {
  flex-direction:column-reverse;
  align-items:stretch;
  margin:var(--space-m, 1.25rem) 0;
  display:flex;
  justify-content:space-between;
  gap:0.5rem;
}
figure > figcaption {
  padding:0;
  line-height:1;
  text-align:center;
}
figure.is-indexed figcaption::before {
  content:"Figure " counter(figures) ": ";
}

Some folks love this. But why?

Below is that same CSS. But weʼve alphabetized the properties. Weʼve added whitespace to make the property name and its value easier to distinguish. And blank lines separate the selectors. The reduction in cognitive load is measurable.

figure {
  align-items: stretch;
  display: flex;
  flex-direction: column-reverse;
  gap: 0.5rem;
  justify-content: space-between;
  margin: var(--space-m, 1.25rem) 0;
}

figure > figcaption {
  line-height: 1;
  padding: 0;
  text-align: center;
}

figure.is-indexed figcaption::before {
  content: "Figure " counter(figures) ": ";
}

Proper whitespacing and more makes CSS much easier to read.

Grouping concerns

We can apply this same proximity principle to our “concerns”. We put our content, structure, and semantics in one place. Then we put our instructions for presentation somewhere separate, but nearby.

In still a third location we put our algorithmic behavior. That behavior might be transferring data to a back end with fetch. Or it might be altering structure, semantics, or style on the fly. Or validating user input.

We can do this grouping in a single file, or we can spit our code out into files of different types. But there is another way we can group like code: into reusable components.

Working with a component architecture

The aim of all programming is to break complex problems down into simpler problems. And to continue breaking them down until they become comprehensible and solvable.

Then to compose the solutions into a single solution to the original problem.

In short, much of the skill in programming is not the coding itself. It is the problem analysis in which we decide where to make the cuts. This is problem decomposition.

A common guide for how to do this is the Single Responsibility Principle. You may know this as part of the SOLID design principles. We can apply this principle well beyond the limits of Object-Oriented Programming (OOP).

True, the single responsibility principle comes from OOP. But it is actually about modularization of code. At the most basic level we have utility functions and components. On the front end, these components generally provide UI widgets.

We can then compose our components into larger groups of components. Call them modules. This enhances resuability, but it also is vital for reducing cognitive load. And each component (or function) should do one (1) thing well.

In Part 2 of this article, we give a good example of what not to do.

DOM to JSON and back

Charles F. Munat — Sun, 14 Jan 2024 22:26:07 +0000

We can persist and rehydrate DOM objects with simple vanilla JS.

5-6 minutes, 1332 words, 4th grade

Here we will create two simple but powerful JavaScript functions.

The first, jsToDom, will take a JavaScript (or JSON) object and turn it into a DOM object that we can insert into our page. The second, domToJs, does the reverse. It takes a DOM object and converts it to JS.

Now we can stringify it and persist it in our database. And rehydrate it at will.

As you may know, JSON does not recognize functions. So we will need a way to deal with our event listeners. Donʼt worry! Weʼve got it covered.

Check out our example of DOM to JSON and back in action. We will explain it below.

A key axiom of Craft Code is less is more. This influences several of the Craft Code methods, such as code just in time and keep it simple.

This means that we donʼt rush to load up dozens of frameworks, libraries, and other dependencies. Instead, we start with nothing: zero dependencies.

We build the site structure with semantically-correct and accessible HTML. Then we add just enough CSS to make it attractive, user-friendly, and responsive.

Finally, we add JavaScript to progressively enhance the user experience. But only if we need it.

This vanilla approach works very well. One goal of the Craft Code effort is to see how far we can go before we have to add a dependency on someone elseʼs code.

The code

For the impatient, letʼs take a look at the final code. Then weʼll explain it. The next two functions are the totality of the module. The rest are specific to this example.

Note: this is about concepts, not production-ready code. This is a first pass and might could use some refactoring. YMMV.

// ./modules/js-to-dom.js
export default async function jsToDom (js) {
  const { attributes, children, events, tagName } = js
  const elem = document.createElement(tagName)

  for (const attr in attributes) {
    elem.setAttribute(attr, attributes[attr])
  }

  if (Array.isArray(children)) {
    for (const child of children) {
      typeof child === "object"
        ? elem.appendChild(await jsToDom(child))
        : elem.appendChild(document.createTextNode(child))
    }
  }

  if (events) {
    for (const key in events) {
      if (!events[key]) {
        break
      }

      const handler =
        typeof events[key] === "function"
          ? events[key]
          : (await import(`./${events[key]}.js`)).default

      handler && elem.addEventListener(key, handler)
    }

    setDataEvents(elem, js.events)
  }

  return elem
}

function setDataEvents (elem, obj = {}) {
  const eventString = Object.keys(obj)
    .reduce((out, key) => {
      if (typeof obj[key] === "string") {
        out.push(`${key}:${obj[key]}`)
      }

      return out
    }, [])
    .join(",")

  if (eventString) {
    elem.setAttribute("data-events", eventString)
  }
}

We grab the tagName from the JSON and create a DOM element of that type. Then we add the attributes to that element. Then we apply jsToDom recursively on the children, appending them to the element.

The events object is pretty clever, IOHO. The keys are the names of the events (e.g., click) and the values are the names of the handler functions. We will import those functions only when needed. See an example below.

We also create a string representation of the events object. We could have simply stringified it, but we wanted to make it human readable, so we wrote our own (lines #39 to #52).

// ./modules/dom-to-js.js
export default function domToJs (dom) {
  const { attributes, childNodes, tagName } = dom

  const eventList = dom.getAttribute("data-events")

  const events = eventList?.split(",").reduce((out, evt) => {
    const [key, value] = evt.split(":")

    if (key) {
      out[key] = value
    }

    return out
  }, {})

  const attrs = Object.values(attributes)
    .map((v) => v.localName)
    .filter((name) => name !== "data-events")

  return {
    tagName,
    attributes: attrs.reduce((out, attr) => {
      out[attr] = dom.getAttribute(attr)

      return out
    }, {}),
    events,
    children: Array.from(childNodes).map((_, idx) => {
      const child = childNodes[idx]

      return child.nodeType === Node.TEXT_NODE
        ? child.nodeValue
        : domToJs(child)
    }),
  }
}

This is a bit tricky as nothing in the DOM is simple. Go figure. We explain below.

This extracts the attributes, the childNodes, and tagName from the passed DOM element. Then we use these to create a simple JS/JSON object, recursing through the child nodes.

We pull the data-events attribute out and treat it separately. We parse the value back into an actual object and add it at the events key.

The output is JS, but we can stringify it to JSON as required. The JSON shown below is a typical example. It creates our test form.

{
  "tagName": "FORM",
  "attributes": {
    "action": "#",
    "method": "POST",
    "name": "form"
  },
  "events": {
    "focusin": "log",
    "submit": "parse-submission"
  },
  "children": [
    {
      "tagName": "TEXTAREA",
      "attributes": {
        "data-type": "json",
        "name": "json"
      },
      "children": [
        "{\"tagName\":\"DIV\",\"attributes\":{\"class\":\"sb-test\",\"data-type\":\"string\",\"id\":\"sb-test-id\"},\"events\":{\"click\":\"log\"},\"children\":[{\"tagName\":\"STRONG\",\"children\":[\"Bob's yer uncle.\"]}]}"
      ]
    },
    {
      "tagName": "BUTTON",
      "attributes": {
        "aria-label": "Run this baby",
        "type": "submit"
      },
      "children": [
        "Run"
      ]
    }
  ]
}

We import this JSON and pass it to jsToDom in our index.js file below.

// index.js
import jsToDom from "./modules/js-to-dom.js"
import formJson from "./modules/form-json.js"
import outJson from "./modules/out-json.js"

export async function injectForm () {
  const main = document.querySelector("main")

  main.appendChild(
    await jsToDom(outJson),
  )

  main.appendChild(
    await jsToDom(formJson),
  )
}

globalThis.addEventListener("DOMContentLoaded", injectForm)

Pretty self-explanatory. Now, how do we handle our events?

Simple. We take our events object from the passed JSON/JS. Then we loop through the keys, which are the event types. The values are the names of the handler functions.

We add an event listener for each type and assign it the default function from the module with that name. For example, our output div gets a click handler called “log”. This function is in ./modules/log.js.

We import the handler: (await import("./log.js")).default. We assign it to handler.

Then we add it like this: addEventListener("click", handler).

Drop dead simple. And we only import the modules that we need. See the actual log handler below.

// ./modules/log.js
export default function log ({ target }) {
  console.log(
    target?.tagName,
    target?.innerText || target?.value
  )
}

Kinda dumb, but it is merely an example. We add this log function as a click handler on our output strong element and as a focusin handler on our form.

The submit handler for the form is a bit more exciting:

// ./modules/parse-submission.js
import domToJs from "./dom-to-js.js"
import jsToDom from "./js-to-dom.js"

export default async function (event) {
  event.preventDefault()

  const form = event.target
  const textarea = form.querySelector("textarea")
  const out = document.querySelector(".out")

  const js = JSON.parse(textarea.value)

  out.appendChild(await jsToDom(js))

  const newForm = domToJs(form)

  document.querySelector("main").appendChild(
    await jsToDom(newForm)
  )
}

We canʼt store functions in JSON, so we put them into modules. Then we will import them as needed when we rehydrate the DOM elements.

We attach parseSubmission as the submit handler for our form element.

What can we do with this?

Ooo. All sorts of cool things.

Easy element creation

Instead of messing around with createElement, setAttribute, etc., we can use jsToDom. We pass it a JS or JSON object representing the DOM elements we want.

We create handler functions ahead of time in modules. When we need an event listener, jsToDom imports it just in time and assigns it to the element.

This works like Reactʼs createElement function. Or a library such as hyperscript. Sure, weʼd prefer JSX for its much reduced cognitive load. But our alternative here is the DOM methods such as createElement. Unless we want to load up a bulky library such as React, that is.

We donʼt.

Suppose I wanted to inject a password field with a show/hide button. First, we create a toggle handler such as this:

// ./modules/toggle-visibility.js
export default function (event) {
  const button = event.target
  const div = button.closest(".form-field")
  const input = div?.querySelector("input")

  if (input) {
    if (input.type === "password") {
      input.type = "text"
      button.innerText = "hide"
      button.setAttribute("aria-label", "Hide password.")
      return
    }

    input.type = "password"
    button.innerText = "show"
    button.setAttribute("aria-label", "Show password.")
  }
}

Now I can call jsToDom with the following JSON and it will create my password input. Try pasting it into the example form. Remember that the click event handler is already available at ./modules/toggle-visibility.js.

{
  "tagName": "DIV",
  "attributes": {
    "class": "form-field"
  },
  "events": {
    "click": "log"
  },
  "children": [
    {
      "tagName": "INPUT",
      "attributes": {
        "type": "password"
      }
    },
    {
      "tagName": "BUTTON",
      "attributes": {
        "aria-label": "Show password.",
        "class": "xx-toggle-password",
        "type": "button"
      },
      "events": {
        "click": "toggle-visibility"
      },
      "children": ["show"]
    }
  ]
}

We hope that it is straightforward how all this works.

Easy element persistance

What if I want to save current UI state? We can use domToJs to do just that.

We took the example page (linked above) and passed the html element to domToJs. Then we stringified it. Now we have preserved both the head and body elements.

So we can take a blank HTML document like this:

<html lang="en">
  <head>
  </head>
  <body>
    <script src="./modules/make-page.js" type="module"></script>
  </body>
</html>

And we can use our persisted JSON head and body elements to create the page on the fly. We can store the JSON in a database or load it from an API.

Below is the code minus the JSON. Or view the actual code.

Then see it in action. View the source on that page to see what we mean.

import jsToDom from "./js-to-dom.js"
globalThis.addEventListener("DOMContentLoaded", async () => {
  const h = document.documentElement.querySelector("head")
  const b = document.documentElement.querySelector("body")

  h.replaceWith(await jsToDom(/* head JSON here */))

  b.replaceWith(await jsToDom(/* body JSON here */))
})

A whole page generated from simple JSON!

Data-driven user interfaces

One idea that we have been promoting for several years now is that of a data-driven interface. Weʼve got an article in the pipeline on that coming soon. But we can give a quick overview here.

The idea is quite simple. The easiest example to visualize is automated form rendering.

Forms collect data. Typically, that data is then persisted in a database.

Databases have schemas. That means that the database already knows the types it expects. If we have defined our schema well, then it knows those types precisely.

Particular data use particular interface widgets. For example, an email address would use an input element of type “email”. An integer might use an input element of type “number” with its step attribute set to “1”.

An enum might use a select or radio buttons or a checkbox group.

From this schema we should be able to determine how to both display and validate that data. After all, there is only a small number of widgets.

So what if the response to our database query for the data included the schema? Some GraphQL queries already make this possible. From that schema, we can generate validation functions. And we know which widgets to display.

So we can generate our form and our validators automatically.

Best of all, we have a single source of truth: our database schema.

In a coming article, we will explain how easy it is to achieve this.

(There is an advanced version of this that uses a SHACL ontology and a triple store such as Fuseki. We then use SPARQL queries to generate the HTML, CSS, and JS straight from the database. Wee ha! Weʼll get to that sometime soon, too. Promise.)

If anyone requests it, weʼll give a detailed explanation of the above code in a separate article. This one is long enough.

Adding simple PubSub, part 2

Charles F. Munat — Mon, 01 Jan 2024 21:50:46 +0000

From event delegation to true pubsub.

Less than 5 minutes, 1178 words, 4th grade

In our previous article we built a simple event delegation system. Our intent was to develop that into a full PubSub system. We can use this PubSub system to create an event-driven architecture.

It will be better if we split the event delegation feature from the PubSub part so we are clear what weʼre doing. We can begin by creating a listeners object to replace our subscriptions object. Weʼll store our listeners here:

export default {}

We will also rename our subscribe function to register. We will move the event listener callback into our register function:

import castEvent from "./cast-event.js"
import listeners from "./listeners.js"

export default function (eventType, id, callback) {
  const type = castEvent(eventType)

  listeners[type] ??= {}

  if (! Object.keys(listeners[type]).length) {
    document.body.addEventListener(type, function (event) {
      const id = event.target?.id
      const type = event.type

      event.target && listeners?.[type]?.[id]?.(event)
    })
  }

  listeners[type][id] = callback
}

It should be obvious what this does (see our previous essay). Now letʼs change our unsubscribe function to an unregister function:

import castEvent from "./cast-event.js"
import listeners from "./listeners.js"

export default function (eventType, id) {
  const type = castEvent(eventType)

  delete listeners?.[type]?.[id]

  if (! Object.keys(listeners[type] || {}).length) {
    delete listeners[type]
  }
}

Again, this works exactly the same as our previous unsubscribe function. Now we have moved our event delegation system into itʼs own module. Now to our PubSub system.

Note that after we unregister the last listener, we clean up after ourselves.

As a reminder, here is our castEvent function code:

export default function (type) {
  if (type === "blur") {
    return "focusout"
  }

  if (type === "focus") {
    return "focusin"
  }

  return type
}

Adding the PubSub system

We copied the code above into new files. This left our previous pubsub files. So, we already have our basic PubSub module. But we will need to update them a bit.

The subscriptions shared object remains as before:

export default {}

Our unsubscribe function is also as before. But as we are no longer dealing with browser events, we donʼt need the castEvent function anymore. Those browser events go to our event delegator system above, not to PubSub.

We have no ID, but weʼll want a way to unsubscribe, so we generate a UUID and return that from our subscribe function.

import subscriptions from "./subscriptions.js"

export default function (topic, callback) {
  subscriptions[topic] ??= {}

  if (Object.keys(subscriptions[topic]) < 1) {
    document.body.addEventListener(
      topic,
      (event) => {
        for (
          const cb of Object.values(subscriptions[topic])
        ) {
          cb(event)
        }
      },
      true
    )
  }

  const token = crypto.randomUUID()

  subscriptions[topic][token] = callback

  return token
}

This is pretty self-explanatory, I hope. Our subscribe function takes two parameters:

the event type to listen for, e.g., EMAIL_UPDATED
the callback function to call when some component publishes an event of this type

We will decide which events to publish and to subscribe to. The nice thing about a PubSub system is that we can create any event we like. We are not limited to browser events.

First, we ensure that there is an object associated with this subscription type.

If this is the first subscription of this type, then we add a listener for this event type. Our callback loops through all the individual callbacks stored in the subscriptions object. It calls each in turn, passing the current event object.

Then we generate a random UUID as our token. We use this to assign the passed-in callback to this topic and token (line #16). Finally, we return the token for use by the unsubscribe function.

What about our unsubscribe function? It is simple as can be:

import subscriptions from "./subscriptions.js"

export default function (topic, token) {
  delete subscriptions?.[topic]?.[token]

  if (Object.keys(subscriptions[topic]) < 1) {
    delete subscriptions[topic]
  }
}

We take as parameters the topic and the token. Then we delete the callback for that topic/token in the subscriptions object.

Finally, if there are no remaining subscribers for that topic, we delete the topic.

Now we need a publish function to allow us to publish to custom events. Here it is:

export default function (topic, detail = {}) {
  const customEvent = new CustomEvent(
    topic,
    {
      bubbles: false,
      detail,
    }
  )

  document.body.dispatchEvent(customEvent)
}

We pass the topic, which is our custom event such as EMAIL_UPDATED. And we pass a detail object. This is the data that our custom event will carry. It could be anything. See our examples below.

On lines #2 to #8, we create a CustomEvent. We assign it our topic as the event type. This is what our subscribers are listening for. We also pass the detail object and set event bubbling to false.

Then on line #10 we call dispatchEvent on the document.body element to dispatch our custom event. By dispatching it and listening for it on the body element, we do not need to bubble it.

Our PubSub system in action

We add the PubSub system to our window (globalThis) object. We add a single object representing our namespace, _xx. Then we add our various modules to that:

import listeners from "./modules/listeners.js"
import publish from "./modules/publish.js"
import register from "./modules/register.js"
import subscribe from "./modules/subscribe.js"
import subscriptions from "./modules/subscriptions.js"
import unregister from "./modules/unregister.js"
import unsubscribe from "./modules/unsubscribe.js"

globalThis._xx ??= {}

Object.assign(globalThis._xx, {
  listeners,
  publish,
  register,
  subscribe,
  subscriptions,
  unregister,
  unsubscribe,
})

console.info("« PubSub and event delegation enabled. »")

[There must be a better way to do this. Ideas?]

Weʼve set up an example of the PubSub system in use. You can see the various modules there:

Now letʼs set up a simple test page. Imagine that we have a set of individually-editable fields, such as name, email, and phone:

<form id="name-editor">
  <label for="name">Name</label>
  <input id="name" name="name" type="text" />
  <button type="submit">Update</button>
</form>
<form id="email-editor">
  <label for="email">Email</label>
  <input id="email" name="email" type="email" />
  <button type="submit">Update</button>
</form>
<form id="phone-editor">
  <label for="phone">Phone</label>
  <input id="phone" name="phone" type="tel" />
  <button type="submit">Update</button>
</form>

And we will include some temporary elements to permit us to display our events:

<pre id="name-output"></pre>
<pre id="email-output"></pre>
<pre id="phone-output"></pre>

Now in our script we first import the PubSub module and then register our event listeners for submit:

<script src="./index.js" type="module"></script>
<script type="module">
  globalThis.addEventListener(
    "DOMContentLoaded",
    async () => {
      globalThis._xx?.register(
        "submit",
        "name-editor",
        (event) => {
          event.preventDefault()

          globalThis._xx?.publish("NAME_UPDATED", {
            id: event.target.elements.name.id,
            name: event.target.elements.name.value,
          }
        )
      },
    )

    // register submit listeners for email and phone, too
  })
</script>

First, we import our PubSub system as a module. Then we add a DOMContentLoaded event listener to run our registration code after the DOM loads.

Next we use the register function of our event delegation system to register a submit handler. This listens for a submit event on the form with the passed ID of “name-editor”. On submit, it calls the passed callback, which:

prevents the default submission so that we donʼt reload the page
calls the publish PubSub function to publish our custom event. We will give it the type NAME_UPDATED. And weʼll pass a details object with the id and value of the input.

We do the same thing for the email and phone fields. Now, when we submit any of these mini-forms, PubSub will create a custom event and publish it to our PubSub system.

We can now subscribe to these events anywhere in our app. And when a component publishes that event, then we can do nothing, one thing, or many things.

Our forms donʼt know who is listening to their events. Our subscribers donʼt know (or care) who is raising these events or why. We have decoupled our code. The PubSub system acts as an event bus to pass around these events. And we can make up any events we need.

Now, to show how it works, we will add subscribers. These will post the stringified events to the pre elements we added above:

<script type="module">
  globalThis.addEventListener(
    "DOMContentLoaded",
    async () => {
      // register event listeners that publish custom events

      const first = globalThis._xx?.subscribe(
        "NAME_UPDATED",
        (event) => {
          const pre = document.querySelector("pre#name-output")

          pre.appendChild( 
            document.createTextNode(
              JSON.stringify({
                type: event.type,
                detail: event.detail,
              }, null, 2) + "\n\n"
            )
          )
        },
      )

      // subscribe to EMAIL_UPDATED and
      // PHONE_UPDATED events as well
  })
</script>

Here we call the subscribe function of our PubSub module. We pass it the topic to which we wish to subscribe. And we pass a callback function to call when a component raises that topic.

In our example callback function, we grab the pre element for that event. Then we stringify the event detail and append it as a child to that element.

You can try this yourself on our example test page.

Of course, this is a simple example. We can do much more with this. For example, we can include much more detail about the event. We can also have more generic or more specific events. We could also:

Allow handlers to delete themselves after a specific number of calls (e.g., once)
Broadcast an event to all topics
Use BroadcastChannel to pass events between browser tabs or windows
Use websockets (or similar) to pass events between different devices

In part 3 of this series, weʼll extend the system a bit. Stay tuned.

Adding simple PubSub, part 1

Charles F. Munat — Wed, 13 Dec 2023 04:23:39 +0000

PubSub is a great way to decouple components.

4 minutes or so, 1037 words, 4th grade

One of the most important Craft Code principles is loose coupling (or decoupling). If we organize our code into loosely-coupled modules, then we can swap them out with ease. We can refactor them, update them, reduce tech debt.

In general, the more we can split our code into simple modules, the better. We can treat them as black boxes. But then we will need a way for them to communicate.

An excellent way is via an event bus, or a publish-subscribe (PubSub) system. This is a tried-and-true design pattern. It has been around since, hmm, Amenhotep (Egyptian dude). Or thereabouts.

We can build a simple pubsub module in JavaScript. Then we can use that to connect our components to each other. And we can do it without any component having to “know” any other component. Thatʼs loose coupling.

So letʼs get to it. And in successive parts, weʼll see how it all fits together.

Our simple pubsub module

First, weʼre gonna need a place to put our subscriptions. This should work:

export default {}

All we need to track our subscribers is a shared object. Thus, our subscriptions module exports an empty object literal. We can share this across our other modules.

Doesnʼt get much easier than that!

We will add our subscribers to this object by event type and element ID. We need a subscribe function to let us do that:

import eventListener from "./event-listener.js"
import subscriptions from "./subscriptions.js"

export default function (type, id, callback) {
  subscriptions[type] ??= {}

  if (! subscriptions[type].length) {
    document.body.addEventListener(type, eventListener)
  }

  subscriptions[type][id] = callback
}

You can see from the code that we begin by importing our subscriptions module. This is no more than a plain JavaScript object.

Then we create an anonymous function that we export as the default. This is our subscribe function. In it, we ensure that our event type exists as an object inside the subscriptions object. If not, we assign an empty object literal to that key. For example, subscriptions["click"] = {}.

OK, so are we already listening for this event type? If we have no subscribers yet, then we can assume not. So we add an event listener to the body element listening for that type of event. We pass it an eventListener function. Weʼll call this function when the user triggers that event. We discuss the eventListener function below.

Finally, after exiting the conditional, we set a property on the type object. The key is the ID of the element weʼre watching. Our callback function is the value. Example: a “click” event on an element with ID of “my-button.” Like this: subscriptions["click"]["my-button"] = eventListener.

What, then, does this eventListener function do? Here it is:

import subscriptions from "./subscriptions.js"

export default function (event) {
  const id = event.target?.id

  event.target && subscriptions?.[event.type]?.[id]?.(event)
}

This is a very simple function. It takes the passed event. Then it extracts the ID of the target element. Finally, it uses the event.type and that ID to get the callback function from the subscriptions. We call the callback function and pass it the event.

Done.

Of course, weʼll also need to be able to unsubscribe:

import subscriptions from "./subscriptions.js"

export default function (type, id) {
  subscriptions[type] ??= {}

  delete subscriptions[type][id]

  if (! Object.keys(subscriptions[type])?.length) {
    delete subscriptions[type]
  }
}

Our unsubscribe function works like the subscribe function but in reverse. Who knew?

We import the subscriptions model. Then we export an anonymous function as default. This is our unsubscribe function.

It first ensures the the type key (our event type) exists in the subscriptions object. Then we use the delete operator to remove the ID key from that object, if it exists. Finally, we check to see if there are any remaining keys in that type object. If not, we delete that object as well.

How it works

Letʼs create a button we can use to trigger an event:

<button id="do-it">Do it!</button>

Rather than adding our click event listener to the element itself, we can use our PubSub system. We will subscribe to click events on the element with ID “do-it” instead:

import subscribe from "./modules/subscribe.js"

subscribe(
  "click",
  "do-it",
  () => console.log("Click on do-it element."),
)

Wait … what about the pub in PubSub?

Ah ha! Good catch. Where is our publish function?

Hmm. Our simple PubSub module is actually only half an implementation. What we have here is more event delegation. It is the browser that does the publishing by raising events. All we do is to subscribe to those events.

Guess what Part 2 of this essay involves.

But before we go there, there are some problems with this model. Event delegation is efficient and the way to go, but not all events bubble up to the body. Sigh … nothingʼs perfect.

The two that we most want to handle are focus and blur. The good news is that we can use focusin and focusout on the body to do the same thing. But it would be nice if module users could still think focus and blur.

So we can update our functions to map one set of terms to the other. We will need a mapper function. We can extend this later as necessary.

export default function (type) {
  if (type === "blur") {
    return "focusout"
  }

  if (type === "focus") {
    return "focusin"
  }

  return type
}

We can update our subscribe function:

import castEvent from "./cast-event.js"
import eventListener from "./event-listener.js"
import subscriptions from "./subscriptions.js"

export default function (eventType, id, callback) {
  const type = castEvent(eventType)

  subscriptions[type] ??= {}

  if (! subscriptions[type].length) {
    document.body.addEventListener(type, eventListener)
  }

  subscriptions[type][id] = callback
}

And weʼll need to do the same to our unsubscribe function:

import castEvent from "./cast-event.js"
import subscriptions from "./subscriptions.js"

export default function (eventType, id) {
  const type = castEvent(eventType)

  subscriptions[type] ??= {}

  delete subscriptions[type][id]

  if (! Object.keys(subscriptions[type])?.length) {
    delete subscriptions[type]
  }
}

We will continue this in Part 2. Meanwhile, here is a simple, vanilla JS example.

Open up the browserʼs DevTools console and then click on the “DO IT!” button. Nothing should happen. Now click the “SUBSCRIBE” button. Youʼve now subscribed to clicks on the “DO IT!” button. Click DO IT!. This time you should see a message in the console.

Now click the “UNSUBSCRIBE” button. You have unsubscribed and further clicks on DO IT! will have no effect.

You can also see how the castEvent mapping works. Take a look at the page source.

On lines #96 to #102 you can see how we subscribed to the focus and blur events on the SUBSCRIBE button. Tab to the button (or click on it) to focus it, and then tab away. You should see messages in the console to show that you focused then blurred the button.

Nice, eh?

Letʼs enhance our forms

Charles F. Munat — Mon, 04 Dec 2023 10:28:04 +0000

Start with workable HTML forms, then make them better.

Less than 6 minutes, 1487 words, 4th grade

In our previous article we showed how to create a form in HTML that validates input. And does so without using JavaScript or an external library.

Check out the example form from that article that validates input without JS.

Hiding and showing the password

Now, how can we use a bit of JavaScript to enhance the experience of our form? Well, one common enhancement is to add the ability to hide and show the password. So letʼs do that. To keep it simple, we'll strip out the other fields.

<div class="xx-form-field" id="xx-password-field">
  <label
    class="xx-field-label"
    for="xx-password-input"
    id="xx-password-label"
  >
    Password
  </label>
  <br>
  <div class="xx-field-help" id="xx-password-help">
    Four or more space-separated words of 4+ characters.
  </div>
  <input
    aria-labelledby="xx-password-help xx-password-label"
    class="xx-field-input xx-password-field"
    id="xx-password-input"
    name="password"
    pattern="[a-zA-Z]{4,}( [a-zA-Z]{4,}){3,}"
    required=""
    size="36"
    type="password"
  >
</div>

We are going to assume that the above is pretty self-explanatory at this point. If not, read the previous article linked above.

The easiest way to do this is to add a button. When clicked, our button will toggle the password field type. Now password, now text. Easy peasy.

globalThis.addEventListener("DOMContentLoaded", function () {
  const field = document.querySelector("#xx-password-field")
  const label = field.querySelector("label")
  const input = field.querySelector("input")
  const button = document.createElement("button")

  button.type = "button"
  button.classList.add("xx-toggle-password")
  button.innerText = "show"
  button.setAttribute("aria-label", "Show password.")

  button.addEventListener("click", () => {
    if (input.type === "password") {
      input.type = "text"
      button.innerText = "hide"
      button.setAttribute("aria-label", "Hide password.")
      return
    }

    input.type = "password"
    button.innerText = "show"
    button.setAttribute("aria-label", "Show password.")
  })

  label.appendChild(button)
})

Letʼs go through this step by step. Itʼs pretty simple.

We begin by adding an event listener to our globalThis object to run on “DOMContentLoaded”. We pass it an anonymous arrow function that will add the enhancement to the password field.
In our arrow function, we begin by setting four const variables:
1. We use document.querySelector to get the outer <div> element of our field using its ID. We assign this to “field.”
2. Using the query selector on the field itself, we get the <label> and <input> elements by tag name. We assign them to “label” and “input” variables, respectively.
3. Finally, we use document.createElement("button") to create a <button> element. We assign it to a variable with name, “button.” Note our careful naming to make it easy to understand our code.
Now we want to configure our button. As this is different from declaring and assigning variables, we leave a blank line. This makes the separation of concerns obvious. Then we:
1. Set the button type to “button” to prevent it from submitting our form when activated. Kind of important, no?
2. Use button.classList.add("xx-toggle-password") to add a CSS class to the button. This makes it easy to style it.
3. Set button.innerText to label the button, “show.”
4. Finally, set an aria-label on the button to “show password.” This makes the buttonʼs function clearer to users of screen readers.
Now we have our button. We want to add an event listener to toggle the password field type when the user clicks the button. Weʼll leave another blank line. Then we will create our event handler as an anonymous arrow function. We assign it to the buttonʼs click event.
1. We use button.addEventListener("click", ...) to assign the arrow function to the buttonʼ click event.
2. In our arrow function, we will need to handle two conditions: one when we have masked the input and one where we havenʼt. The safest way to test this is by checking the type of the input. Ergo, we check that the input type is “password,” type === "password", our default state.
3. If the condition returns true (type is “password”), then we:
  1. set the input type to “text”,
  2. set the buttonʼs innerText to “hide”,
  3. and set the aria-label to “hide password”.
4. Then we return from the function. The password should now be visible and the button should say, “HIDE.”
5. If the condition fails, i.e., the input type isnʼt “password,” then we have unmasked the field. So we:
  1. set the type back to “password”,
  2. set the buttonʼs innerText back to “show”,
  3. and of course, our aria-label back to “show password.” And thereʼs our toggle.
Last but not least, we add our button to the form with label.appendChild(button). As a screen reader reads our label aloud, so, too, will it read the buttonʼs aria-label.

As we say, easy peasy.

Why not a component library?

“But … but … but …” we can hear some readers say, “why not just use a pre-coded field from a popular component library?”

And, “why would we want to have to write this code every time we wanted an enhanced password field?”

Why on Earth would we do that? Or on Mars, for that matter?

I put this field together once. I use Astro for its bundling benefits: it makes a component architecture easy. I have no need for its “islands” architecture. So, I have been building my own component library bit by bit (pun intended).

Although I shun passwords as much as practicable, it pays to have a field like this. So I added a PasswordField to my Astro component library.

And I included a prop called allowShow. When it is true, then the component includes the JS enhance script and features a “SHOW” button. When it is false or missing, the component does not.

Easy peasy, as I may have said once or twice before. And the benefit is obvious:

I know every line of the code.

I wrote it, and the responsibility for making sure it is bug-free, accessible, user-friendly, etc. is on me. I am not counting on devs I have never met to keep my codebase current, robust, and secure.

And because it is an ad hoc component — written specifically to fill my needs — rather than a highly-abstracted, one-size-fits-all attempt to please everyone, it can be small and efficient. No superfluous parts. William of Ockham would be proud.

Case in point:

<div class="MuiFormControl-root css-kzv9dm">
  <label
    class="MuiFormLabel-root MuiInputLabel-root MuiInputLabel-formControl MuiInputLabel-animated MuiInputLabel-shrink MuiInputLabel-sizeMedium MuiInputLabel-filled MuiFormLabel-colorPrimary MuiFormLabel-filled MuiInputLabel-root MuiInputLabel-formControl MuiInputLabel-animated MuiInputLabel-shrink MuiInputLabel-sizeMedium MuiInputLabel-filled css-1rgmeur"
    data-shrink="true"
    for="filled-adornment-password"
  >
    Password
  </label>
  <div class="MuiInputBase-root MuiFilledInput-root MuiFilledInput-underline MuiInputBase-colorPrimary MuiInputBase-formControl MuiInputBase-adornedEnd css-1thjcug">
    <input
      aria-invalid="false"
      id="filled-adornment-password"
      type="password"
      class="MuiInputBase-input MuiFilledInput-input MuiInputBase-inputAdornedEnd css-ftr4jk"
      value=""
    />
    <div class="MuiInputAdornment-root MuiInputAdornment-positionEnd MuiInputAdornment-filled MuiInputAdornment-sizeMedium css-1mzf9i9">
      <button
        class="MuiButtonBase-root MuiIconButton-root MuiIconButton-edgeEnd MuiIconButton-sizeMedium css-slyssw"
        tabindex="0"
        type="button"
        aria-label="toggle password visibility"
      >
        <svg
          class="MuiSvgIcon-root MuiSvgIcon-fontSizeMedium css-vubbuv"
          focusable="false"
          aria-hidden="true"
          viewBox="0 0 24 24"
          data-testid="VisibilityIcon"
        >
          <path
            d="M12 4.5C7 4.5 2.73 7.61 1 12c1.73 4.39 6 7.5 11 7.5s9.27-3.11 11-7.5c-1.73-4.39-6-7.5-11-7.5zM12 17c-2.76 0-5-2.24-5-5s2.24-5 5-5 5 2.24 5 5-2.24 5-5 5zm0-8c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3z"
          ></path>
        </svg>
        <span class="MuiTouchRipple-root css-w0pj6f"></span>
      </button>
    </div>
  </div>
</div>

To be fair, the MUI folks have improved their code in many ways over the past several years. Now they use the proper data- attribute format. They have discovered aria- attributes as well.

They even have an aria-label attribute. That said, “toggle password visibility” is wordy and fails to make clear the current state of the field. Is it unmasked or masked?

There remain several UX problems, but weʼll save those for another article.

What is most noticeable about the above code is the excessive number of CSS class names. Why on Earth do we need so many?

Well, here is the root of the problem. MUI must abstract beyond belief so that anyone can use it for anything. This is not an MUI problem; it is a component library problem.

The irony is that MUI was once based on Material Design, and still is to some degree. But they have wrangled it to the point that you could make it look like an old Windows 95 form if you wanted to.

But why? My sites each have a specific look and feel. I have a design system for each. I do not need an enormous stylesheet and a million classnames to make them look and work in different ways. Ways that I will never need.

I give each relevant HTML element one class — maybe two. Then I write my stylesheet to set the specific style for my design system.

It gets worse

Oh, but thereʼs more.

Where is the CSS for this field? Where is the JavaScript?

Why, they have bundled them away somewhere else. Good luck finding them. Good luck changing them.

Instead, MUI provides a complex system for configuring their components. Hey, you are no longer a programmer or even a developer. You are now a configurer.

Fun, right?

If you want this field to work some way that the MUI folks didnʼt allow for, then good luck. I have spent many painful hours trying to force MUI to fit some designerʼs style preference. Oh, the PTSD!

But when we code the field ourselves with simple HTML, CSS, and JavaScript, then it is all right there.

A recent fad — devs can never leave well enough alone — is something called LoB, Locality of Behavior. LoB states that the behavior of a unit of code should be as obvious as possible by looking only at that unit of code.

I guess multiple screens and the ability to put several files side-by-side was the wrong path. Silly me.

But with my Astro component model, I could, if I wanted to (I donʼt), create a Single-File Component (SFC). That would put the CSS, JS, and HTML all in the same “PasswordField.astro” file.

Me? I prefer to keep structure/semantics, style/layout, and behavior separate. In separate files. And with roughly 10ha of screen real estate at my workstation, I can refer to side-by-side files quickly as I work.

So my Astro PasswordField component has a folder called “PasswordField” and three files:

PasswordField/
- index.astro
- index.css
- index.ts

I import the CSS and TypeScript files at the top of my Astro file. Astro builds the component, transpiles the TS to JS, and bundles and dedupes all the CSS and JS.

We can do a lot more with simple JavaScript enhancements. But it might surprise you how little we need to do so.

In a coming article, we will show how many HTML form components are already quite enhanced enough.

Native form validation is easy

Charles F. Munat — Wed, 29 Nov 2023 01:44:14 +0000

You can validate your forms without JavaScript.

Less than 6 minutes, 1470 words, 4th grade

It is easy to create web forms that validate themselves without JavaScript. Why so many developers ignore this native capability is an open question.

I guess that when all you have is React or similar, then everything looks like a React component.

But what happens when the user disables JavaScript (or it is otherwise unavailable)? OK, you are rendering your React components on the server. Nice. But what happens to your client-side validation?

But before we get into this, a brief digression. Letʼs take another look at our previous article, Progressive enhancement.

The `requestAnimationFrame` option

After I published that article, I got a suggestion from a good friend. He recommended that I animate the accordion elements with requestAnimationFrame. So I tried it:

function toggleAccordion (event) {
  event.preventDefault()

  const summary = event.target
  const accordion = summary.closest("details")
  const content =
    accordion.querySelector(".xx-accordion-content")
  const openHeight = summary.xxOpenHeight

  if (accordion.open) {
    function shutAccordion (
      height,
      stopHeight = 0,
      decrement = 20
    ) {
      return function () {
        content.style.maxHeight = `${height}px`

        if (height <= stopHeight) {
          accordion.open = false

          return
        }

        requestAnimationFrame(
          shutAccordion(
            height - decrement,
            stopHeight,
            decrement
          )
        )
      }
    }

    shutAccordion(openHeight)()

    return
  }
  function openAccordion (
    height,
    stopHeight,
    increment = 10
  ) {
    return function () {
      content.style.maxHeight = `${height}px`

      if (height >= stopHeight) {
        return
      }

      requestAnimationFrame(
        openAccordion(
          height + increment,
          stopHeight,
          increment
        )
      )
    }
  }

  accordion.open = true

  openAccordion(0, openHeight)()
}

I wonʼt go into a lot of detail here as it is pretty self-explanatory. We create open and close outer functions that return an inner closure. requestAnimationFrame calls that closure recursively. In this way, we can increment or decrement the height on each frame immutably.

Is this a potential performance bottleneck, creating all those closures? Maybe. But itʼs the simplest way to do it, and we donʼt prematurely optimize here at Craft Code. If it turns out to be a bottleneck, weʼll switch to a loop and a mutable variable.

Betcha it works just fine.

But which is better? setTimeout? Or requestAnimationFrame?

Itʼs a pretty close call. setTimeout is older and will work in browsers such as Internet Explorer pre-v10. Of course we can polyfill that.

An argument for requestAnimationFrame is that it may be smoother. Especially if there are many simultaneous animations on the page. It also may be more performant. Donʼt need to support very old browsers? Then requestAnimationFrame is probably the better way to go.

You should ask, “Where in the world are my users? What browsers are they using?” That will help you to determine which option is best. But then we should always start with that question, right?

Try it on our example animation frame accordion.

About those forms

Letʼs get to our forms. A few simple recommendations to start.

Donʼt use placeholders. Just donʼt. Use <label> instead. Set the for attribute to the id of the input labelled.
Group related controls in <fieldset> elements. Use the <legend> element to label the group. Fieldsets are easily styled with CSS these days.
Ensure that your form elements are keyboard navigable. And in the same order that they appear visually. Donʼt confuse your users.
You can best determine other considerations, such as where to put buttons or which buttons to use, with user testing. There is no one right way.

With those caveats in mind, let us begin with a simple form. Here is one with which we are all familiar … but not for much longer, we hope.

<form
  action=""
  class="xx-form"
  method="GET"
  name="simple-form"
>
  <fieldset class="xx-fieldset">
    <legend>Please sign in</legend>

    <div class="xx-form-field">
      <label
        class="xx-field-label"
        for="email"
        id="xx-email-label"
      >
        Email address
      </label>
      <br>
      <div class="xx-field-help" id="xx-email-help">
        The email address with which you signed up.
      </div>
      <input
        aria-labelledby="xx-email-help xx-email-label"
        class="xx-field-input xx-email-field"
        id="email"
        name="email"
        required
        size="36"
        type="email"
      >
    </div>

    <div class="xx-form-field">
      <label
        class="xx-field-label"
        for="password"
        id="xx-password-label"
      >
        Password
      </label>
      <br>
      <div class="xx-field-help" id="xx-password-help">
        Four or more space-separated words of 4+ characters.
      </div>
      <input
        aria-labelledby="xx-password-help xx-password-label"
        class="xx-field-input xx-password-field"
        id="password"
        name="password"
        pattern="[a-zA-Z]{4,}( [a-zA-Z]{4,}){3,}"
        required
        size="36"
        type="password"
      >
    </div>
  </fieldset>

  <button
    class="xx-submit-button"
    type="submit"
  >
    Sign in
  </button>
</form>

As in previous examples, we use CSS class names on all our elements. The xx- is a namespace, i.e., cc- for Craft Code. This allows us to select our elements in our CSS and avoids collisions.

We like grouping controls in fieldsets, and using the legend for the title of our form. We group our labels and inputs in <div> elements with the class name, xx-form-field. This permits us to style them as a group.

Our view is that best practice is to put the label above the input. To make this work even when the user disables CSS, we use a <br> element. Note that we tie our labels to their inputs with the for attribute.

Whenever possible, we choose our HTML elements to take advantage of browser features. We chose an <input> of type email rather than type text. Because of this, the browser will validate the value of the input on submit.

If the value is not a potentially valid email address, then submission fails.

We also set the required attribute on the input. The form will require a valid email address before we can submit it.

One down.

Then for the password field, we choose the password type, which masks the characters as we type them. We also set the required attribute so the user must provide a password. We could use minlength to set a minimum length for the password, but we have a better idea.

As this brilliant xkcd comic makes clear, a better approach to passwords is to use four random words. To this end, we have used the pattern attribute on the password input. It requires the password to be four or more space-separated words of four or more characters each.

The pattern: [a-zA-Z]{4,}( [a-zA-Z]{4,}){3,}.

Of course, we make this requirement clear with a help message above the input. There a screen reader will announce it before entering the field. And to be extra certain, we associate it with the input via the aria-labelledby and id attributes as shown.

Hereʼs what that looks like:

Here are the possibilities:

Empty input (required): “Please fill out this field.”
bob@: “Please enter a part following '@'. 'bob@' is incomplete.”
@dobbs: “Please enter a part followed by '@'. '@dobbs' is incomplete.”
bob.dobbs: “Please include an '@' in the email address. 'bob.dobbs' is missing an '@'.” (As above.)

Here is what happens if the password doesnʼt match our pattern:

Here are the possibilities:

Empty input (required): “Please fill out this field.”
Bob is yer uncle: “Please match the requested format.”

Be sure that you explain what the “requested format” is! Donʼt make your users guess!

Try “correct horse battery staple”. Does it work? xkcd would be proud.

Give this simple form a try.

What else can we validate?

Different types of input provide different validations. Here are some examples:

Pattern mismatch: You can use the pattern attribute with other input types as well. These include: email, search, tel, text, and url.
Range overflow/underflow: You can set max and min values on types date, datetime-local, month, number, range, time, and week.
Step mismatch: You can set the step value (a number) on types date, datetime-local, month, number, range, time, and week. Sheesh! Who knew there were so many input types? MDN provides a handy list of default values.
Too long/short: You can set a maxlength and/or minlength (as a number of characters) on types email, password, search, tel, text, and url.

Donʼt try to memorize these. Remember: code (and learn) just in time. There is no point in wasting time and effort that you may never need.

Instead, first design your form. Then determine what needs validation. Finally, refer to Mozilla Developer Network or equivalent to see what fits your needs.

For example, you might create an integer input like this:

<input
  id="iq"
  max="210"
  min="0"
  name="iq"
  required
  step="1"
  type="number"
>

This accepts only positive integers between 0 and 210 (the highest IQ on record). The step value of 1 does not prevent entering decimals, such as 100.1. But try submitting that. Youʼll get a warning:

“Please enter a valid value. The two nearest valid values are 100 and 101.”

You can try it on our example form. What happens if you enter -50? What about 300?

You could also do this with an input of type text by setting the pattern attribute to [0-9]*. Or use ([0-9]|[1-9][0-9]*)? if you want to disallow starting zeros. But either way you lose the semantic value of the number type.

Our recommendation: stick with the number input.

The key takeaway here is this: good enough is, by definition, good enough.

Too often, designers and devs create bloated, ugly, brittle, incomprehensible code. We do it because we want to tweak our interface in some minor way, but plain HTML doesnʼt make it easy. So we hack the heck out of it.

The temptation to throw out all the benefits of semantic, accessible, browser-native code just to make it a bit slicker can be overwhelming. But resist, resist, resist!

This isnʼt about UX. Your users donʼt care about your flashy interface, no matter what they tell you when you ask. Thatʼs your ego talking.

Users care about usability, findability, comprehensibility, accessibility.

Can they find what they are looking for? Can they understand it when they find it? Can they make your site do what they want it to do?

And we can manage all that with an elegant design without having to hack the code. Simple and beautiful. And more stable, less likely to be buggy, and be easier to code and refactor, too.

And if they never see your flashy, edgy new design, they will never miss it.

Progressive enhancement

Charles F. Munat — Mon, 20 Nov 2023 09:31:36 +0000

8-9 minutes, 2161 words, 5th grade

Now that weʼve seen how semantic HTML alone produces a fully-responsive web page, where do we go next?

Our plain HTML page is ugly as sin, so weʼre gonna need some CSS to spiff it up. But today letʼs keep the CSS simple. Weʼll return to good CSS practices soon in a follow-up article.

Progressive enhancement starts with something that is already functional and usable. Then it adds just enough JavaScript to enhance that functionality.

In this essay weʼll take a simple <details> element, which will work in any browser, and make it into an accordion. The <details> element with its <summary> is already an accordion. But it doesnʼt look like one.

Start with the HTML

To begin, letʼs start with some essential HTML:

<details class="xx-accordion">
  <summary class="xx-accordion-summary">Always visible</summary>
  <div class="xx-accordion-content">
    <p>Hidden content</p>
    <p>More hidden content</p>
  </div>
</details>

You can see an example page here.

No doubt you have spotted the class attributes. We prefer to apply CSS by class. We can fall back to class-and-tag-name if we need more specificity, as youʼll see below.

So whatʼs up with the “xx-” prefix?

Simple. To avoid name clashes with imported CSS, we namespace our classes. For example, the Craft Code site might use “cc-” as in cc-accordion.

Adding the initial CSS

Letʼs add a bit of CSS to give it that “accordion” look and feel. Here we go:

.xx-accordion {
  background-color: #fafafa;
  border-radius: 5px;
  border: 1px solid #747481;
  color: #2c2c30;
}

.xx-accordion-summary {
  background-color: #0d4872;
  color: #fafafa;
  font-size: 1.25rem;
  margin: 0;
  padding: 1rem;
}

.xx-accordion-content {
  border-top: 1px solid #747481;
  padding: 0 1rem;
}

Again, we provide an example page.

This is already a workable accordion component. But most accordions have more than one expandable element. So letʼs add a few more elements:

<div class="xx-accordion-group">
  <details class="xx-accordion">
    <summary class="xx-accordion-summary">
      Katherine Johnson
    </summary>
    <div class="xx-accordion-content">
      <p>
        <a
          href="https://en.wikipedia.org/wiki/Katherine_Johnson"
          rel="external"
        >Creola Katherine Johnson</a> was an American
        mathematician whose calculations of orbital mechanics
        as a NASA employee were critical to the success of
        the first and subsequent U.S. crewed spaceflights.
      </p>
    </div>
  </details>
  <details class="xx-accordion">
    <summary class="xx-accordion-summary">
      Dorothy Vaughan
    </summary>
    <div class="xx-accordion-content">
      <p>
        <a
          href="https://en.wikipedia.org/wiki/Dorothy_Vaughan"
          rel="external"
        >Dorothy Jean Johnson Vaughan</a> was an American
        mathematician  and human computer who worked for the
        National Advisory Committee for Aeronautics (NACA), and
        NASA, at Langley Research Center in Hampton, Virginia.
      </p>
    </div>
  </details>
  <details class="xx-accordion">
    <summary class="xx-accordion-summary">
      Mary Jackson
    </summary>
    <div class="xx-accordion-content">
      <p>
        <a
          href="https://en.wikipedia.org/wiki/Mary_Jackson_(engineer)"
          rel="external"
        >Mary Jackson</a> was an American mathematician and
        aerospace engineer at the National Advisory Committee
        for Aeronautics (NACA), which in 1958 was succeeded by
        the National Aeronautics and Space Administration (NASA).
      </p>
    </div>
  </details>
</div>

We have also adjusted the CSS a bit to make it work with multiple elements:

.xx-accordion-group {
  border-radius: 5px;
  border: 1px solid #0d4872;
  padding: 0;
}

.xx-accordion {
  background-color: #fafafa;
  color: #2c2c30;
}

.xx-accordion-summary {
  background-color: #0d4872;
  border-bottom: 1px solid #fafafa;
  color: #fafafa;
  font-size: 1.25rem;
  margin: 0;
  padding: 1rem;
}

.xx-accordion:last-child summary {
  border-bottom: none;
}

.xx-accordion-content {
  padding: 0 1rem;
}

We added the .xx-accordion-group properties. And moved the outer border from the individual elements to the group. We also changed the border color to match the <summary> background color.
We removed the top border from the content block. Then we replaced it with a bottom border on the <summary> element. We also changed the color to the background color of the <details> elements. This makes it appear as a horizontal rule between the accordion elements.
We donʼt want that bottom border on the last element in the accordion group. So we used .xx-accordion:last-child summary to remove that one bottom border.

Here is the full accordion example.

Enhancing our accordion

Rats! The accordion elements open and close instantly when you click on the summary. It would be nice if we animated the open and close.

We bet that your first thought will be that we can do this with CSS animations. We thought so, too. But it turns out that it is fiendishly difficult to make that work. By that we mean that we couldnʼt. Sigh.

CSS should always be your first choice for effects, but when CSS fails you, JavaScript steps up. We can do it the way we used to.

CSS transitions for the loss

Naturally, the first thing we tried was a CSS transition on the height of the content block. But this only works if you know the height of the block in advance. It wonʼt work (for us, anyway) with height set to auto or fit-content.

OK, fine! Instead we set the open height to a CSS property with a fallback to auto: var(--xx-accordion-height, auto). That oughta do it.

Now we need to set that property for each accordion element separately. Enter JavaScript!

JavaScript to the rescue

The first thing we want to do is write a function that grabs any and all accordion elements on the page. Then weʼll add an event listener to each of them. And we want our function to run once as soon as the DOM has finished loading.

Here, then, is our first pass at the JavaScript:

function enhanceAccordions () {
  const nodes = document
    .querySelectorAll(".xx-accordion-content")

  for (let node of nodes) {
    node.style =
      `--xx-accordion-height: ${node.clientHeight}px`
  }
}

globalThis.addEventListener(
  "DOMContentLoaded",
  enhanceAccordions
)

And our modified CSS:

.xx-accordion-content {
  height: 0;
  overflow-y: hidden;
  padding: 0 1rem;
  transition: height 0.5s ease-in-out;
}

.xx-accordion[open] .xx-accordion-content {
  height: var(--xx-accordion-height, auto);
  transition: height 0.5s ease-in-out;
}

And it does work. Beautifully … the first time we open an accordion element. And then it stops working. And it doesnʼt animate the close at all. Why not?

Because toggling the <details> element sets “open” to false and thatʼs that.

Slam.

OK, fine. Time to show it whoʼs boss.

Kicking butt and taking names

First, letʼs delete the CSS we added. Forget using a transition! Weʼll do this the old-fashioned way.

First issue: when the <details> element toggles shut, it closes the accordion abruptly. We need to prevent that. To do so, we will seize control.

Instead of handling the toggle event, letʼs capture the click on the <summary> element. Then we will prevent the click from bubbling up.

We still need to know the height of the open accordion, but we donʼt need it in our CSS. So letʼs use a property instead. Weʼll call it xxOpenHeight. (Do remember to replace xx with your own namespace.)

function toggleAccordion (event) {
  console.log(event.target.xxOpenHeight)
}

function enhanceAccordions () {
  const nodes = document.querySelectorAll(".xx-accordion")

  for (let node of nodes) {
    const summary = node.querySelector("summary")
    const content = node.querySelector(
      ".xx-accordion-content",
    )

    if (content) {
      summary.xxOpenHeight = content.clientHeight
    }

    summary?.addEventListener("click", toggleAccordion)
  }
}

globalThis.addEventListener("DOMContentLoaded", enhanceAccordions)

Check out the enhanced example and open the browser console. Note how clicking on the a summary prints the height of that accordionʼs content block to the console. Weʼre off to a good start.

Now letʼs complete the toggleAccordion function to animate the accordion elements. Weʼll explain this code line by line below.

function toggleAccordion (event) {
  event.preventDefault()

  const summary = event.target
  const accordion = summary.closest("details")
  const content = accordion.querySelector(".xx-accordion-content")
  const openHeight = summary.xxOpenHeight

  if (accordion.open) {
    content.style.maxHeight = `${openHeight}px`

    function shutAccordion() {
      const maxHeight = parseInt(content.style.maxHeight, 10)

      if (maxHeight > 0) {
        content.style.maxHeight = maxHeight < 25
          ? "0"
          : `${maxHeight - 25}px`

        setTimeout(shutAccordion, 10)

        return
      }

      accordion.open = false
    }

    shutAccordion()

    return
  }

  content.style.maxHeight = "0px"

  function openAccordion() {
    const maxHeight = parseInt(content.style.maxHeight, 10)

    accordion.open = true

    if (maxHeight < openHeight) {
      content.style.maxHeight = `${maxHeight + 15}px`

      setTimeout(openAccordion, 10)
    }
  }

  openAccordion()
}

We need to prevent the element from toggling. We can do this with event.preventDefault() on line #2 above. Now we are responsible for opening and closing the accordion ourselves.
Next, we use the event.target to get the <details>(accordion) element, our content block, and the xxOpenHeight. Lines #4-7.
Now we have two possibilities. Either the accordion is open and we want to close it, or vice versa. So we check if the accordion is open on line # 9.
We need the maxHeight property of the content blockʼs style attribute. We will use it to control the height of the block. So if the accordion is open, then we must make sure that maxHeight it is set to xxOpenHeight. See line #10.
Now we will use setTimeout recursively to reduce the maxHeight bit by bit. Weʼll call it every few milliseconds until we have shut the accordion. We create our shutAccordion function on lines #12-26.
Hmm … maxHeight is a string. Urk. So we will convert it to a number with parseInt to decrement it. Then weʼll recreate the string. We get the integer on line #13. If our maxHeight is still greater than zero, we subtract 25 from it on lines #16-18. Then we call our shutAccordion function recursively. We set the timeout to 10 milliseconds. Thatʼs a nice frame rate.
When the maxHeight reaches zero, we set accordion.open to false (line #25) and weʼre good to go.
Now that weʼve defined our shutAccordion recursive function, we need to call it to start the recursion (animation). We do so on line #28.
But what if the accordion is closed? Then we set the maxHeight to zero on line #33 to be sure. This also covers the initial case.
We define our openAccordion recursive function on lines #35-45.
Again, we begin by parsing the height from maxHeight on line #36. And we immediately set the accordion to “open” on line #38. This has no visual effect yet because the height of the content block is currently zero.
Now, on lines #40-44, if the maxHeight is still less than the measured openHeight, we add 15 pixels to the maxHeight. Then we call the function again using setTimeout to delay for 10 milliseconds. When the content block is fully open, this conditional will fail and the recursion will stop.
And, as with the shutAccordion function above, we have to call the function to start the animation. We do this on line #47.

Not that difficult!

Putting it all together

Try the final example above. You might note an issue with the content of the content block becoming visible instantly. This happens even though the height is zero.

That is because we havenʼt hidden the overflow. We can do that by adding overflow-y: hidden to the .sb-accordion-content CSS.

Once we do that, then our accordion should animate flawlessly. Now disable JavaScript in the DevTools of your browser. Check it out. It still works. It just doesnʼt animate. But we can live with that, right?

And if you disable both CSS and JavaScript, then it still works fine! It even works on the Lynx text-only browser, which doesn't recognize the <details> element. But that just means that the accordion is always open.

Again, we can live with that.

Thatʼs progressive enhancement for you. Our code is simple and responsive and works for everyone. And if you have CSS and JS enabled, then you get a nicer experience.

Reponsive by default

Charles F. Munat — Tue, 14 Nov 2023 03:01:01 +0000

Until we use CSS to wreck it, that is.

Many developers believe that it is tricky to ensure responsiveness in web design. And that achieving a design that works on any screen resolution or aspect ratio is difficult.

Too many developers are not willing to make that effort. The consequence? Poorly-coded websites everywhere you look.

Unresponsive? Whereʼs a defibrillator when you need one?

Anyone who uses a smart phone to surf the internet encounters such sites daily. Unless like many people you hate the public sphere and spend all your time on Big Tech sites such as F**k or Instagram.

But here is a secret that many web developers have forgotten, if we ever knew it:

HTML is responsive by default.

What that means is this:

More often than not, we use CSS to destroy responsiveness rather than to maintain or enhance it.

Itʼs not intentional, of course. Few realize that thatʼs what weʼre doing even as we do it. And this is because we start construction with the roof instead of the foundation.

First we use CSS to destroy responsiveness. Then we add a few media query hacks to try to get back some semblance of it. HTML is often an afterthought. All we need are <div> and <span> elements, right? Lots of ʼem.

It is like designing a car by building the skin first, then trying to force the engine, drivetrain, etc. to fit. You can do it that way, but it wonʼt be comfortable, safe, or maintainable.

Better to build it from the wheels up for performance and safety, and then to find an attractive body to fit over it. Why not do it right from the outset?

We can make our sites both responsive and attractive by following a simple approach. Donʼt code outside-in. Code inside-out.

Start with the foundation

Begin by creating your component, page, or even the whole site in semantic HTML. No CSS at all. No JavaScript.

Add the <!DOCTYPE> and the <html> (donʼt forget the lang attribute), <head>, and <body> elements. Then add the viewport and charset <meta> elements and a <title> to the <head> element.

Here, then, is your page foundation:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta
      content="width=device-width, initial-scale=1" 
      name="viewport"
    >
    <title>Responsive by default</title>
  </head>
  <body>
    <!-- content goes here -->
  </body>
</html>

Now youʼre ready to be responsive by default.

Build the body next. Start with the landmark elements. At the top level is <main>. Note how all the virtual DOM libraries screw this up by putting a <div> at the top level. They donʼt care about correct HTML. But coding by hand we can get it right.

Add the other landmark elements as needed: <header> and <footer> and optionally a <nav> element. Nest these in <main> if you prefer.

Hundreds of articles and tutorials have explained how to nest heading elements. Itʼs easy! Yet more than half of all web sites still get it wrong. Why? Craft Coders get this right.

Moving on, you may want an element with nested <section> elements. And, of course, properly nested <h1> to <h6> elements. How about an <aside>? Is there a <form>? Be sure that your use of each is correct and standards compliant.

How do you know if youʼve done this right? Many HTML tools will allow you to see your page hierarchy. Here is the Craft Code home page. But possibly the quickest way is to use the HTML5 outliner extension. Here is what the HTML5 outline of the Craft Code home page looks like:

You can see that it is a proper page hierarchy with correctly-nested heading elements.

The best resource for HTML help that weʼve found is Mozilla Developer Network (MDN). Of course, the final arbiter is the HTML standard itself.

Work your way down through your page hierarchy. Use the correct semantic element for the type of content. For example, an <address> element for a street address.

Parse through the text mentally and ask, What is this? Is there a way to make clear to the browser the type of this content with a semantic HTML element?

How many of these do you know? How many do you use regularly?

<p> for paragraphs, <a> for links, <button> for buttons.
<details> and <summary> for text that might not be of interest. We can hide it but keep it available to the user.
<ol> with <li> for ordered lists—lists in which the order of elements matters.
<ul> with <li> for unordered lists—lists in which the order of elements doesnʼt matter.
<dl>, <dt>, and <dd> with <dfn> (if a definition) for description lists or glossaries.
<figure> with <figcaption> for figures. They are more common than you might think. Great way to caption images, charts, graphs, etc.
<form>, <fieldset>, <legend>, <label>, <input>, <textarea>, <select>, <option>, <optgroup>, <datalist>, and <button> for forms. Do you know what all these do? Why not use them properly?
<table>, <caption>, <thead>, <tbody>, <tfoot>, <col>, <colgroup>, <tr>, <th>, <td> for tabular data. And only for tabular data. You will rarely need a table. Avoid when possible.
<picture>, <source>, and <img> for your images. Or <img> with the srcset attribute. Donʼt forget the alt attribute. Consider wrapping these in <figure>.
There are many other worthwhile flow elements, such as:
- <code> for programming code.
- <pre> for pre-formatted text.
- <mark> for highlighted text. (Great with search results.)
- <ins> and <del> for insertions and deletions.
- <abbr> for abbreviations. Use the title attribute for the expansion of the abbreviation.
- <em> and <strong> for emphasis and strong emphasis.
- <q> and <blockquote> for quotations (inline and block, respectively).
- <cite> for citations. Have you ever used this one? But you must have cited someone at some time. No?
- <sub> and <sup> for subscript and superscript letters, respectively (great for footnotes).
- <time> for dates and times. Again, ever used it?
- a few more obscure elements: <kbd> for keyboard input. <samp> for <samp> (from a computer program). <var> for mathematical variables.

Why is it that so many of us try to represent the semantics of these data with CSS alone? We can encode the semantics right into the HTML with ease and then add the visuals with CSS by tag name.

But most devs—letʼs be honest—who want to apply a style to a time will add a <span> element and a utility class. The <time> element? Eh! Never heard of it.

Or weʼll mark up a quotation by adding quotation marks rather than using the <q> element. Donʼt we know that the <q> element can add the quotation marks for us? And that we can use CSS to choose the quote style?

body {
  quotes: "“" "”" "‘" "’";
}

And how many of us have remembered to cite the source?

<q
  cite="https://craft-code.dev/essays/code/responsive-by-default"
>
  <abbr title="HyperText Markup Language">HTML</abbr>
  is responsive by default.
</q>

But how does an actual page look? Iʼve created a responsive-by-default example to illustrate.

Is it ugly as sin? You bet. But is it usable? Iʼd argue yes. More importantly, is it responsive? Well, here it is on my phone. Try it on yours.

Ugly, true. But usable on any screen or screen reader.

We can also take a look at the page using the Lynx text-only browser. No CSS. No JS. No images. Nothing but text. So does it work? Take a look:

What about performance?

So. How does this score in Lighthouse?

So thatʼs looking pretty g… whoa! What the heck is up with that 88?

Well, partly it is because we have added the <meta content="noindex" name="robots"> element to the <head>. This prevents search engines from indexing the page. We donʼt want users landing on this example page thinking that it is an actual site page! But if we remove that, we still achieve only a 95%. What gives?

This is actually a problem with the browser. Chromeʼs default stylesheet does not enforce a minimum “tap size” for links and buttons. The links in the unordered lists are too closely spaced (by browser default). Chrome oughta give more room for fat fingers. Like mine.

But users can zoom, we will fix it with CSS, and it is hard to imagine a phone user without CSS. So weʼll leave it. (We could wrap the links in <p> elements to get that space, but thatʼs a hack, so weʼll avoid it.)

There we have it. Responiveness is not something we add to our web pages. It is something we destroy—if weʼre not careful and thoughtful as we code. Keep it responsive.

Are you a CRAFT Coder?

Charles F. Munat — Sun, 05 Nov 2023 23:37:18 +0000

Craft Code is code made with care, skill, and ingenuity. It is as simple as it can be and no simpler. It is state-of-the-art, elegant, and bespoke.

So are you a Craft Coder?

You may be a Craft Coder if ...

You follow these four practices. (There are many more, but these are the essentials.)

1. You put quality before quantity

This is not to say that quantity (speed) is unimportant. But the way to achieve speed is by improving your skill, not by rushing.

Long ago I was a fitter/welder building rail cars. When I started, my foreman told me to build bolsters, a part of the car. I was very slow and sloppy. I could build three per day working as hard as I could.

The old guy next to me appeared to be standing still. No rush at all. And yet he built ten impressive bolsters per day every day. WTF?

My boss told me not to worry about it. Focus on quality and speed will come, he said.

A year later I set the company record at fourteen bolsters in a day, and every one was flawless.

The mistake that new devs make is to focus on speed and to allow themselves to write sloppy code. Craft Coders know better.

Practice does not make perfect. Practice makes permanent. Repeat the same mistakes over and over, and you donʼt get any closer to Carnegie Hall. ~ Sarah Kay

2. You keep things as simple as practicable, but no simpler

Occam's Razor is a famous dictum: do not needlessly multiply entities. This is often paraphrased as "the simplest solution is the best".

But that's wrong.

If that were the case, then a simple bad solution would be better than a more complex good solution. Huh?

The key word is "needlessly". What William of Ockham was saying was, "the simplest solution all else being equal is the best one". That's a big difference.

If two solutions are equal solutions, then choose the simpler one. Don't add anything you don't need. No gratuitous nuthin'.

That's how a Craft Coder codes.

Complexity is a sign of technical immaturity. ~ Daniel T. Ling

3. You prefer bespoke code whenever practicable.

There are times when commodity code makes more sense. But commodity code is always inefficient. When you use code written by others, they didn't write it for you. They wrote it for a wide variety of coders and situations.

Hence, code that you don't need is endemic to commodity code. There is no escaping it.

Writing specific, bespoke code creates the most efficient, performant code. No needless entities! Assuming, of course, that you are a good enough coder (see #1 above).

Craft Coders are confident, consistent bespoke coders. They can write commodity code, but rather than a first resort, they see it as a last one.

This is not to disparage re-use. Not at all. But first write the code yourself, then re-use it.

Avoid hasty abstractions (AHA). ~ Kent C. Dodds

4. You embrace a comprehensive approach

It is very easy for web developers to suffer from tunnel vision. When all you have is a hammer, everything starts to look like a nail, right?

If you are working in a large enterprise as another cog in the wheel, then that might be for the best. It is assembly-line, commodity code, after all. Keep those blinders on.

But Craft Coders engage themselves in the entire process of web development. And that is so much more than cranking out code.

First, there is accessibility, as specified in the WCAG 2.2 guidelines and related advice. To a Craft Coder, accessibility is not an afterthought, but something foundational. Nothing gets built without putting accessibility first.

And UX, of course, although true accessibility incorporates UX. If an application is not usable, then how can it be accessible?

But as many coders are now starting to realize, the most important approach of all is to make it sustainable. Craft Coders do so without fail. After all, there is little point in remodeling the kitchen if you're busy burning down the house.

Craft Coders consider all aspects of web development in their work. Do you?

There is no Planet B. ~ Mike Berners-Lee (son of Tim)

So, are you a Craft Coder?

If so, speak up. Craft Coding is a noble calling. But if new coders don't hear about it, then our numbers will dwindle. And that will be a sad day for web development.

Weigh in in the comments. What do you think? Are you a Craft Coder or a commodity coder? And why? And no judgement! The world needs commodity coders, too.

Forem: Craft Code

Data-driven UIs

Key takeaway

On this page

Start at the finish

Widget by widget

ID

Name

Email address

Display name on profile

Favorite color

The “Save changes” button

Putting it all together

Adding HATEOAS

Oh, the benefits!

Whatʼs next?

The proximity principle

On this page

The proximity principle explained

Applying the proximity principle to code

Forget separation of concerns

HyperText Markup Language (HTML)

Cascading Style Sheets (CSS)

Grouping concerns

Working with a component architecture

DOM to JSON and back

The code

What can we do with this?

Easy element creation

Easy element persistance

Data-driven user interfaces

Adding simple PubSub, part 2

Adding the PubSub system

Our PubSub system in action

Adding simple PubSub, part 1

Our simple pubsub module

How it works

Wait … what about the pub in PubSub?

Letʼs enhance our forms

Hiding and showing the password

Why not a component library?

It gets worse

Native form validation is easy

The requestAnimationFrame option

About those forms

What else can we validate?

Progressive enhancement

Start with the HTML

Adding the initial CSS

Enhancing our accordion

CSS transitions for the loss

JavaScript to the rescue

Kicking butt and taking names

Putting it all together

Reponsive by default

Start with the foundation

What about performance?

Are you a CRAFT Coder?

You may be a Craft Coder if ...

1. You put quality before quantity

2. You keep things as simple as practicable, but no simpler

3. You prefer bespoke code whenever practicable.

4. You embrace a comprehensive approach

So, are you a Craft Coder?

The `requestAnimationFrame` option