DEV Community: Robert Pearce

Working on the "Ramda Ramp-Up Guide"

Robert Pearce — Thu, 12 Nov 2020 14:51:00 +0000

Hi, folks!

After using ramda since early 2016 and individually helping so many people level up their functional programming in JS, I've decided to write down all the things at https://ramda.guide. This is a work in progress, and I need you to help guide some of the learning.

This opinionated guide will cover topics from beginner to advanced skill levels, as well as best practices learned from using ramda at scale in production since 2016. There will also be interactive examples as you learn!

Where do you come in? Answer any of the following in the comments!

What were your biggest pain points with learning ramda?
What things do you still not quite understand?
What would you like to see in a guide?
How and where do you use ramda?
What else would you like to say on the subject?

If you want to help me further, sign up for updates on https://ramda.guide to get updates about when new content is published (there are also RSS and Atom feeds). This will also help me gauge interest and inspire me to get it done! Content will of course be cross-posted to the https://dev.to community, too.

<3,
Robert W. Pearce

Dear Dia11y: Decorative & functional images

Robert Pearce — Wed, 21 Oct 2020 11:24:36 +0000

Originally posted on https://dear-dia11y.com/decorative-and-functional-images.html.

Dear dia11y,

There have been times in the past where I've used what I'll momentarily call "helper images" like user avatars, button icons, and illustrations, and in trying to make them more accessible, I've given them alternative text like "user avatar" and "rubbish bin". While I should almost always accurately describe and label images, there are times when it's safe for me to mark images as decorative or provide a functional label instead of alternative text.

For my future reference, the W3 website has a few good articles on these subjects:

I'm leaving myself some notes and examples on these subjects below.

Decorative images

If I have an image that doesn't add any extra content to the page, I can probably assume that this image is decorative.

A great example would be user avatars right next to user names (see example just below).

I probably shouldn't label these images "avatar", "user avatar" or even "avatar for ${userName}", for labels like these don't describe the content of the images and therefore likely cannot describe them in a way that adds valuable content to the document.

If I have a list of users with their avatars and names but no explicit descriptions of their avatars, what is the point of announcing "avatar" for each user?

Instead, I can provide an alt attribute of "" to tell assistive technologies that I want to ignore this image.

<li ...>
  <img
    alt=""
    class="..."
    height="60"
    src="..."
    width="60"
  />
  <span>Robert W. Pearce</span>
</li>

If this image is an SVG or any other type of decorative element that might get picked up by a screen reader, I can use aria-hidden="true" to completely hide it from the screen reader, or I can use role="presentation" to effectively set role="none" and remove any existing semantics (I prefer the former approach).

Functional images

There are times when I want to use images as visual aids to accompany actionable text like "Delete email", or perhaps I only want to present an image, but I really intend for that image to mean "Delete email" — note to self: this is called a functional image.

Here is an HTML summary of the example above:

<button type="button" ...>
  <svg aria-hidden="true" ...>
    <!-- ... -->
  </svg>
  <span>Delete email</span>
</button>

The only thing of note is that I have aria-hidden="true" on the <svg>.

While it could be argued that narrating "button, rubbish bin image, Delete email" could give some added context, the image is intended as a visual aid, and labelling it seems to add a bit of noise, distracting from the simple point of what this does: "button, Delete email".

What if I want to only use the image, but I intend for it to mean "Delete email"?

Here is an HTML summary of the example above:

<button aria-label="Delete email" type="button" ...>
  <svg aria-hidden="true" ...>
    <!-- ... -->
  </svg>
</button>

In addition to having aria-hidden="true" on the <svg>, instead of the text node being there, there is an aria-label="Delete email" on the surrounding <button> element. This button will also narrate, "button, Delete email".

That's it for decorative and functional images for today!

Yours,

Robert W. Pearce

Future-proof two types of visually hidden content

Robert Pearce — Tue, 29 Sep 2020 13:35:54 +0000

Originally posted on https://dear-dia11y.com/future-proof-two-types-of-visually-hidden-content.html

Dear dia11y,

I would prefer to not hide content from anyone, but there are times when I need to provide extra context and functionality when a design is not inclusive enough.

The .visually-hidden "clip pattern" from The A11y Project is excellent for hiding content that is intended for screen reader users, and it can be leveraged to provide interactive elements, like <button>s, that reveal themselves on focus for screen reader, keyboard, and other assistive device users alike. Here's what that website's recommendation is:

.visually-hidden:not(:focus):not(:active) {
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}

For most use cases, this is great. But my work in large codebases has shown me that if I want this to not take up any space, I need to get bossy and guard against future changes, as well.

.visually-hidden:not(:focus):not(:active) {
  border: none !important;
  clip-path: inset(50%) !important;
  clip: rect(0, 0, 0, 0) !important;
  height: 1px !important;
  margin: 0 !important;
  overflow: hidden !important;
  padding: 0 !important;
  position: absolute !important;
  white-space: nowrap !important;
  width: 1px !important;
}

While most things I do in my life aren't important to anyone but me, getting visually hidden content right is very !important.

With these additions we can ensure that we don't break any existing designs.

However, what if we transition from one page / view to another and need to call element.focus() on a visually hidden element in order to manage focus context? We might have something like this:

<h1 class="visually-hidden" tabindex="-1">
  A necessary hidden h1 for whatever reason
</h1>

If we call .focus() on that <h1>, the :not(:focus) part of the .visually-hidden definition will cause it to be not hidden!

The .visually-hidden class is intended to be a catch-all to also account for links and buttons, and we definitely want to leverage that, but there are times where we know we will never want it to be focused, so we can be explicit about doing so by having an additional class, .visually-hidden-always, and reuse our code via a grouped selector.

.visually-hidden:not(:focus):not(:active),
.visually-hidden-always {
  border: none !important;
  clip-path: inset(50%) !important;
  clip: rect(0, 0, 0, 0) !important;
  height: 1px !important;
  margin: 0 !important;
  overflow: hidden !important;
  padding: 0 !important;
  position: absolute !important;
  white-space: nowrap !important;
  width: 1px !important;
}

Something important to note is the usage of 1px. I may be tempted to use em or rem or ch or ex or something clever, but I should not do this! Depending on the font-size, the browser, the monitor DPI, etc, something like 0.1em can end up as a half pixel and be rounded down to 0, thus making this inaccessible to screen readers! Use 1px, I beg of my future self; it's okay to use px for certain things.

Yours,

Robert W. Pearce

Figure & Figcaption: Supporting IE11, JAWS, NVDA, & VO

Robert Pearce — Sun, 27 Sep 2020 18:57:56 +0000

Originally posted on https://dear-dia11y.com/figure-and-figcaption-supporting-ie11-jaws-nvda-and-vo.html

Dear dia11y,

At work, I must support IE11 along with all the other major browsers, so that means I need to support JAWS & NVDA across these browsers on Windows in addition to VoiceOver on macOS & iOS Safari (I don't do much in the Android world at the moment).

About 1-2 months ago, I did a lot of work fixing up issues around <figure>s and <figcaption>s. For a refresher, here's the example that MDN uses:

<figure>
  <img
    alt="Elephant at sunset"
    src="/media/cc0-images/elephant-660-480.jpg"
  />
  <figcaption>
    An elephant at sunset
  </figcaption>
</figure>

This is straightforward, but JAWS + IE11 didn't quite recognize this as a figure, and we had issues with the caption because we had a <div> as the parent of the <figcaption>. NVDA + Firefox didn't like this setup, either. Here's what our example was structured like:

<figure>
  <img
    alt="Elephant at sunset"
    src="/media/cc0-images/elephant-660-480.jpg"
  />
  <div>
    <figcaption>
      An elephant at sunset
    </figcaption>
  </div>
</figure>

After going back and forth with different combinations of elements and attributes, here's what was settled on to make this work across all these browsers and screen readers:

<figure aria-labelledby="caption-id" role="figure">
  <img
    alt="Elephant at sunset"
    src="/media/cc0-images/elephant-660-480.jpg"
  />
  <figcaption id="caption-id">
    An elephant at sunset
  </figcaption>
</figure>

Adding role="figure" to the <figure>, explicitly stating that it was labelled by the <figcaption>, and placing <figcaption> as an immediate child of <figure> resolved all our issues.

This was a helpful table of related compatibility: https://www.powermapper.com/tests/screen-readers/labelling/img-figcaption/

Yours,
Robert W. Pearce

Image with SVG source VoiceOver bug

Robert Pearce — Sun, 27 Sep 2020 18:55:26 +0000

Originally posted on https://dear-dia11y.com/image-with-svg-source-voiceover-bug.html

Dear dia11y,

I recently documented an issue where some decorative illustration <img /> elements with SVG sources were, when using VoiceOver in macOS Safari, announcing every <g> (group) element by narrating the word "image". Here's what the HTML essentially was:

<img
  alt=""
  class="foo"
  src="path/to/file.svg"
/>

The alt="" should have alerted the screen reader that this was a decorative image, but no matter — let's add aria-hidden="true" to it.

I recommended this issue and possible fix to a colleague and forgot about it.

This colleague read up on role="presentation" versus aria-hidden="true" and whatnot and eventually discovered that neither solved the problem! What a mystery.

This person did some digging and discovered that image elements with SVG sources that aren't marked as role="img" can have VoiceOver jump into the SVG document and start reading things.

The fix?

<img
  alt=""
  class="foo"
  role="img"
  src="path/to/file.svg"
/>

That's it! HTML and a11y linters will complain about the repetitive role, but we do what we have to do.

It also turned out that this was a problem with non-decorative images. Image alternative text was being read along with the innards of SVG sources (even <text> elements!).

Here are some nicely documented test cases of the issue:

Yours,
Robert W. Pearce

Hello, accessibility world!

Robert Pearce — Sun, 27 Sep 2020 18:51:44 +0000

Originally posted on https://dear-dia11y.com/hello-accessibility-world.html

Dear dia11y,

Today I started an accessibility blog!

I normally write about functional programming, but I've been doing a lot of accessibility (a11y — a…11 letters…y) work this year, and I thought it would be a good idea to write down some of the useful things I've learned.

Don't worry; these will generally be short.

For this first entry, I'd like to share about one of the most common things I come across: when to use <div>s versus <button>s versus <a>s for "clickable" elements.

Unless I have a very good reason not to follow these rules, it's very simple:

use <a> if it changes the window's location
use <button> if I can press on it and something happens
try to not use <div> as a trigger for anything

If I'm concerned about the default browser styling of buttons, here are CSS styles collected from around the internet that will allow me to reset a button's default styling.

.btn-reset {
  -webkit-appearance: none;
  -moz-appearance: none;
  appearance: none;
  background: none;
  border-radius: 0;
  border: none;
  color: inherit;
  font: inherit;
  margin: 0;
  padding: 0;
}

If I have to use <div>, make sure I remember to read MDN's role=button page and the WAI ARIA Practices 1.2 button specification to figure out how to do it correctly. Most importantly, if I decide I'm going to try to reproduce native browser behavior that all manner of programs and devices rely on, make sure my team and I know how to test it and not break it in the future.

I must confess that I've made and continue to make many a11y mistakes, but it's in learning from our mistakes that we are able to grow.

Yours,
Robert W. Pearce

Hakyll Pt. 6 – Pure Builds With Nix

Robert Pearce — Thu, 30 Apr 2020 12:57:12 +0000

Special thanks to Utku Demir for review and constant inspiration.

This post was originally published at https://robertwpearce.com/hakyll-pt-6-pure-builds-with-nix.html.

This is part 6 of a multipart series where we will look at getting a website / blog set up with hakyll and customized a fair bit.

Pt. 1 – Setup & Initial Customization
Pt. 2 – Generating a Sitemap XML File
Pt. 3 – Generating RSS and Atom XML Feeds
Pt. 4 – Copying Static Files For Your Build
Pt. 5 – Generating Custom Post Filenames From a Title Slug
Pt. 6 – Pure Builds With Nix
(wip) Pt. 7 – Customizing Markdown Compiler Options

Overview

In this post we're going to create a new hakyll site from scratch with a caveat: we will do just about everything with nix in order to guarantee reproducibility for anyone (or anything) using our project. There are also two bonuses that we will inherit simply because we are using nix:

we will not need to rely on global package installs (apart from nix, of course)
we will be able to easily patch any package problems; for example, if some of hakyll's dependencies are not available in nixpkgs, we can patch hakyll to get it to work.

Here is the example repository with what we're going to make: https://github.com/rpearce/hakyll-nix-example

Note: this post assumes that you have installed nix on your system.

Steps to Build Our Hakyll Project With Nix

Make a new project with release.nix, default.nix, and shell.nix, and get into its pure nix shell environment:

λ mkdir hakyll-nix-example && cd $_
λ echo "{ }: let in { }" > release.nix
λ echo "(import ./release.nix { }).project" > default.nix
λ echo "(import ./release.nix { }).shell" > shell.nix
λ nix-shell --pure -p niv nix cacert

We won't have to touch default.nix nor shell.nix again, for we are delegating their responsibilities to the release.nix file that we'll add more to in a moment.

Note: we require nix and cacert when running a pure nix-shell with niv because of this issue: https://github.com/nmattia/niv/issues/222.

Now that we're in the nix shell, initialize niv and specify your nixpkgs owner, repository, and branch to be whatever you want:

[nix-shell:~/projects/hakyll-nix-example]$ niv init
[nix-shell:~/projects/hakyll-nix-example]$ niv update nixpkgs -o NixOS -r nixpkgs-channels -b nixpkgs-unstable
[nix-shell:~/projects/hakyll-nix-example]$ exit

Update your release.nix file with the following:

let
  sources = import ./nix/sources.nix;
in
{ compiler ? "ghc883"
, pkgs ? import sources.nixpkgs { }
}:

let
  inherit (pkgs.lib.trivial) flip pipe;
  inherit (pkgs.haskell.lib) appendPatch appendConfigureFlags;

  haskellPackages = pkgs.haskell.packages.${compiler}.override {
    overrides = hpNew: hpOld: {
      hakyll =
        pipe
           hpOld.hakyll
           [ (flip appendPatch ./hakyll.patch)
             (flip appendConfigureFlags [ "-f" "watchServer" "-f" "previewServer" ])
           ];

      hakyll-nix-example = hpNew.callCabal2nix "hakyll-nix-example" ./. { };

      niv = import sources.niv { };
    };
  };

  project = haskellPackages.hakyll-nix-example;
in
{
  project = project;

  shell = haskellPackages.shellFor {
    packages = p: with p; [
      project
    ];
    buildInputs = with haskellPackages; [
      ghcid
      hlint       # or ormolu
      niv
      pkgs.cacert # needed for niv
      pkgs.nix    # needed for niv
    ];
    withHoogle = true;
  };
}

Don't worry, we'll circle back to what we just did.

Create a hakyll.patch diff file:

λ touch hakyll.patch

Bootstrap the hakyll project (we won't ever need this again):

λ nix-shell --pure -p haskellPackages.hakyll --run "hakyll-init ."

Build the project and --show-trace just in case something goes wrong:

λ nix-build --show-trace

Run the local dev server:

λ ./result/bin/site watch

Navigate to http://localhost:8000 and see your local dev site up and running!

Understanding the `release.nix` File

Let's break down what we copied and pasted into release.nix.

let
  sources = import ./nix/sources.nix;
in
{ compiler ? "ghc883"
, pkgs ? import sources.nixpkgs { }
}:

# ...

The let gives us the space to define an attribute (variable), and it is here that we import our sources.nix file that was generated by niv. The in block defines a function parameter with two attributes, compiler and sources, that each have defaults (when there's a :, that means what comes next is a function body or another function argument). For the compiler, we will use this version to compile all of the Haskell packages that we interact with. For the pkgs, we default to using our pinned version of nixpkgs, but this is overridable.

# ...

let
  inherit (pkgs.lib.trivial) flip pipe;
  inherit (pkgs.haskell.lib) appendPatch appendConfigureFlags;

  # ...

Our new let falls within the function we created above, and we then state that we would like to inherit some nice functions from pkgs.lib.trivial and pkgs.haskell.lib. The flip and pipe functions are standards in functional programming, but I'll share a short recap:

flip takes a function a -> b -> c and flips the accepted arguments to act like b -> a -> c. Its definition is flip = f: a: b: f b a; – it takes a function, then a, then b, and then it applies a and b in reversed (flipped) order.
pipe establishes a set of functions that you can apply data to, one after the other. Think of bash pipes: cat blog_post.txt | grep nix.

let
  # ...

  haskellPackages = pkgs.haskell.packages.${compiler}.override {
    overrides = hpNew: hpOld: {
      hakyll =
        pipe
           hpOld.hakyll
           [ (flip appendPatch ./hakyll.patch)
             (flip appendConfigureFlags [ "-f" "watchServer" "-f" "previewServer" ])
           ];

      hakyll-nix-example = hpNew.callCabal2nix "hakyll-nix-example" ./. { };

      niv = import sources.niv { };
    };
  };

  # ...

This uses our pinned (or overridden) nixpkgs to create our own haskellPackages for a specific Haskell compiler version.

For hakyll, we need to make sure it gets compiled with the watchServer and previewServer flags, or we won't be able to use its local dev server. We also provide an optional patch file (git diff > hakyll.patch file) that we can build hakyll with if there are any changes to the project that we need to make. Patch files can be empty when no patches are required, but if you do need to patch something, here is an example hakyll.patch file:

diff --git a/hakyll.cabal b/hakyll.cabal
index fcded8d..9746f20 100644
--- a/hakyll.cabal
+++ b/hakyll.cabal
@@ -199,7 +199,7 @@ Library
   If flag(previewServer)
     Build-depends:
       wai             >= 3.2   && < 3.3,
-      warp            >= 3.2   && < 3.3,
+      warp,
       wai-app-static  >= 3.1   && < 3.2,
       http-types      >= 0.9   && < 0.13,
       fsnotify        >= 0.2   && < 0.4

The hakyll-nix-example attribute is specifically for our Haskell project in order for us to be sure our project is compiled with our desired compiler version. We leverage the callCabal2nix tool to handle automatically converting our hakyll-nix-example.cabal file into a nix derivation for our build.

Lastly, we ensure that the niv we are using in the nix-shell is our pinned niv that niv itself generated.

let
  # ...

  project = haskellPackages.hakyll-nix-example;
in
{
  project = project;

  # ...

The project attribute is what our default.nix will use when being called with tools like nix-build. All we do is access our hakyll-nix-example attribute from our customized haskellPackages.

let
  # ...
in {
  # ...

  shell = haskellPackages.shellFor {
    packages = p: with p; [
      project
    ];
    buildInputs = with haskellPackages; [
      ghcid
      hlint       # or ormolu
      niv
      pkgs.cacert # needed for niv
      pkgs.nix    # needed for niv
    ];
    withHoogle = true;
  };
}

Exactly like default.nix uses the project attribute, shell.nix is looking for a shell attribute to define everything it needs when running nix-shell --pure. We use shellFor, which comes with the nixpkgs Haskell tools, and we provide it a few attributes:

the packages attribute holds our project package and any other nixpkgs that you would like to have built when entering the shell
the buildInputs attribute holds all the tools that we'll have available to us while we're in the shell; for example, you can run ghcid and load your Haskell code to test it out or run hlint to lint your Haskell files
withHoogle gives us the ability to query https://hoogle.haskell.org

Wrapping Up

Using nix to build our project helps make development consistent and predictable; however, learning nix is not necessarily a breeze. The following articles directly contributed to my understanding that led to this post:

https://nixos.org/nixos/nix-pills/index.html
https://github.com/Gabriel439/haskell-nix/tree/master/project4
https://turbomack.github.io/posts/2020-02-17-cabal-flags-and-nix.html (this article is what led me to learn how to patch hakyll)
overrideAttrs: https://nixos.org/nixpkgs/manual/#sec-pkg-overrideAttrs
overlays: https://nixos.org/nixpkgs/manual/#chap-overlays
https://maybevoid.com/posts/2019-01-27-getting-started-haskell-nix.html
https://kuznero.com/post/linux/haskell-project-structure-in-nixos/
https://github.com/NixOS/nixpkgs/blob/master/doc/languages-frameworks/haskell.section.md
https://nixos.org/nixpkgs/manual/#haskell

Next up:

(wip) Pt. 7 – Customizing Markdown Compiler Options

Thank you for reading!

Robert

Build Your Team an Accessible, Shareable Component Library

Robert Pearce — Mon, 27 Apr 2020 18:19:42 +0000

Orginally posted on https://robertwpearce.com/build-your-team-an-accessible-shareable-component-library.html

Today we're going to dive into building a frontend component library from start to finish that you can share privately with your team or publicly with everyone!

By the end of this post, you will be able to use TypeScript, React, Storybook, and more to provide a simple way to create accessible components that can be included in all of your projects.

If you'd like to skip to the code, here is the example component library we're going to make: https://github.com/rpearce/example-component-library.

Overview

This is a big post that covers a lot of ground, so buckle up.

When Should I Make a Component Library and Why?
Project API (Usage)
Main Project Tools
Project Structure
Component Structure
Creating the Project
TypeScript Setup
Linting Setup
Testing Setup
Storybook Setup
An Example Component
Building Our TypeScript
Building Our CSS
Building Our Stories
Continuous Integration Notes
Publishing Notes

When Should I Make a Component Library and Why?

Scenario 1: Component Entropy

Components make up large parts of our applications. As projects age, components can become increasingly coupled with other components, business logic, and application state management tools like redux.

These components usually start out small, focused, and pure. As time passes and the imperative of timely code delivery takes its toll, these components become harder to compose, harder to reason about, and cause us to yearn for simpler, less-involved times.

Instead of rewriting those components in place and repeating the same process, consider extracting and developing each one in isolation in a library. This will allow you to keep each one's surface area small and keep your business logic, state management, routing logic, etc., where it belongs: in your application.

With this scenario, a good intermediary step, before pulling components into their own project, would be to create a folder in your application for these components and set up a tool like storybook to house the individual examples and compositions of them.

Scenario 2: Multiple Projects (or The Possibility of Multiple Projects)

Consider this exchange:

Them: You know that spinner/widget/dropdown/search thing we have over here? It looks and works great! We want the same thing over here and over here. How difficult is that?

Me: Those are different projects, and that is really more like 4 different components working together, so a) hard to do cleanly but good for the long-term or b) easy (for now) if I copy and paste.

Them: We need to ship.

Me: Okay, so copy and paste it is...

What's special about this exchange is that both sets of concerns and perspectives are valid. Software stakeholders typically want and need to ship features and fixes quickly, and they usually want to maintain brand consistency across their ecosystems. Software developers at those companies want to be able to ship features and fixes and maintain brand consistency, but they are also aware of the cost of short-term decision making (this is a way of accruing technical debt).

We know that even the best code is useless to a business if there are no customers around paying to use it, but we also know that suboptimal tech decision making can grind projects to a halt over time, averting the stakeholder's directive of shipping features and fixes quickly.

So what can we do to not only amend the scenario above but also make this undesired state unrepresentable in the future? We can start our projects with an accompanying component library! For existing projects, we can begin moving them in that direction.

Project API (Usage)

Let's first define how we are going to include our components in our project.

JS Imports

Component JavaScript can be imported in a few different ways:

// import from the main (or module) specification in
// package.json, depending on your bundler and its version
import { Circle } from 'mylib'

// straight from the ESModule build
import Circle from 'mylib/dist/esm/Circle'

// straight from the CommonJS build
import Circle from 'mylib/dist/cjs/Circle'

// straight from the Universal Module Definition build
import Circle from 'mylib/dist/umd/Circle'

CSS Imports

Component CSS can be imported like this:

import 'mylib/dist/css/Circle/styles.css'

If you know you will use all of the components and wish to import all of their CSS at once:

import 'mylib/dist/css/styles.css'

The JS import is simple enough, but you might be wondering, "What's the deal with importing CSS like this? I thought we were on to things like styled-components, emotion, CSS modules, etc?"

These tools are great if the consuming application can bundle up and inject the styles using the same instance of the tool, but can you guarantee each app will use these same styling tools? If so, by all means go that direction. However, if your library is injecting its own styles into the document at runtime, you will not only potentially run into style specificity / collision issues if you don't have the application styles load last, but strict content security policies will potentially disallow the dynamically added styles from even being applied!

The solution? Go with the lowest common denominator: regular, vanilla CSS (or something that outputs regular, vanilla CSS). We'll come back to this in the example component section.

Main Project Tools

It's time to build the project! Here are the main tools we will use:

NodeJS (version 13.13.0)
TypeScript
React
Storybook (UI examples)
jest (testing)
axe-core (testing accessibility)
linting
- eslint with prettier
- husky with lint-staged; only on pre-push

Project Structure

.
├── .storybook            (1)
│   └── ...
├── dist                  (2)
│   └── ...
├── docs                  (3)
│   └── ...
├── examples              (4)
│   └── ...
├── scripts
│   └── buildCSS          (5)
├── source                (6)
│   └── ...
├── .eslintignore
├── .eslintrc.js
├── .gitignore
├── .prettierrc.js
├── CHANGELOG.md          (7)
├── LICENSE               (8)
├── README.md
├── husky.config.js
├── jest.config.js
├── lint-staged.config.js
├── package.json
├── testSetup.ts
├── tsconfig.base.json    (9)
├── tsconfig.cjs.json
├── tsconfig.esm.json
├── tsconfig.json
└── tsconfig.umd.json

.storybook/ – storybook examples configuration
dist/ – compiled project output
docs/ – compiled storybook examples output
examples/ – add create-react-app, gatsby, and other example projects here
scripts/buildCSS – store build scripts here like this CSS-related one
source/ – where your project lives; we'll dive into this in the next section
CHANGELOG.md – be a good teammate and document your library's changes; very useful for your teams and useful if you decide to open source the project
LICENSE – a good idea if you plan to open source; otherwise, put UNLICENSED in your package.json license field
tsconfig.json, et al – typescript build configs; we'll dive into this in the project setup section

Component Structure

.
└── source
    └── ComponentA
        ├── __snapshots__
        │   └── test.tsx.snap
        ├── index.tsx
        ├── stories.tsx
        ├── styles.css
        └── test.tsx
    └── ComponentB
        └── ...
    └── ComponentC
        └── ...
    ├── index.ts
    └── test.tsx

The component and everything to do with it are co-located in the source/ComponentA/ folder:

index.tsx component file (and any additional component files)
storybook stories
CSS
tests

This grouping of everything having to do with a component makes it very easy to find everything you need. If you would prefer a different setup, you can adjust the tool configurations however you like.

Each component is then exported from the main index.ts file.

It's now time to start the project from scratch and make this outline a reality!

Creating the Project

To begin, let's create the project and a package.json file with some project-related information:

$ mkdir example-component-library && cd $_
$ touch package.json

And in package.json:

{
  "name": "@yournpm/example-component-library",
  "version": "0.1.0",
  "description": "Example repository for a shared React components library",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "repository": {
    "type": "git",
    "url": "git@github.com:yourgithub/example-component-library.git"
  },
  "homepage": "https://github.com/yourgithub/example-component-library",
  "bugs": "https://github.com/yourgithub/example-component-library",
  "author": "Your Name <you@youremail.com>",
  "license": "BSD-3",
  "keywords": [],
  "tags": [],
  "sideEffects": ["dist/**/*.css"],
  "files": ["LICENSE", "dist/"],
  "scripts": {},
  "devDependencies": {},
  "peerDependencies": {
    "react": "*",
    "react-dom": "*"
  },
  "dependencies": {}
}

Once you save that, run your build tool to make sure everything is ok:

$ npm install

Notably, we've set our main field to dist/cjs/index.js, the CommonJS build, for compatibility with NodeJS environments because they don't yet work well with ESModules. We've set our module field to look at dist/esm/index.js, the ESModule build. If you want to make use of the Universal Module Definition build we'll create later on, you can use the browser field: "browser": "dist/umd/index.js". Personally, if I build with webpack, I want webpack to select the module field over the browser one because it will always be of a smaller size, for the UMD builds are meant to be run in any of a few different environments.

Also of importance is the sideEffects field. If our library code was pure and didn't have side effects, we would set the value to false, and build tools like webpack would prune away all of the unused code. However, since we also are exporting CSS, we need to make sure that it doesn't get dropped by the build tool, so we do that with "sideEffects": ["dist/**/*.css"].

Lastly, we know we're going to be using React, so we can go ahead and set that as a peerDependency (it's up to you to decide what versions of React you'll support).

TypeScript Setup

We can now add TypeScript to our project with some compiler and project-related options. We'll also add some type definition libraries that we'll use later, as well as a dependency on tslib to make compiling our code to ES5 seamless.

$ npm install --save-dev --save-exact \
  @types/node \
  @types/react \
  @types/react-dom \
  typescript
$ npm install --save --save-exact tslib
$ touch tsconfig.base.json tsconfig.json

We will place our compilerOptions in tsconfig.base.json so that they can be extended in all our different builds in the future:

{
  "compilerOptions": {
    "allowJs": false,
    "allowSyntheticDefaultImports": true,
    "declaration": true,
    "esModuleInterop": true,
    "importHelpers": true,
    "jsx": "react",
    "lib": ["es2020", "dom"],
    "moduleResolution": "node",
    "noImplicitAny": true,
    "outDir": "dist/",
    "sourceMap": false,
    "strict": true,
    "target": "es5"
  }
}

Note that the importHelpers flag tells tslib whether it should be enabled or not.

The tsconfig.json will be used as a default to include our future source directory:

{
  "extends": "./tsconfig.base.json",
  "include": ["source/**/*"]
}

We'll add some more TypeScript-related packages when we get to the tools that need them, and we'll add more TypeScript build configurations in the section on building our typescript.

Linting Setup

Linting is a great way to have everyone adhere to the same set of rules for code style. For our project, we're going to install a few tools to help us out.

$ npm install --save-dev --save-exact \
  @typescript-eslint/eslint-plugin \
  @typescript-eslint/parser \
  eslint \
  eslint-config-prettier \
  eslint-plugin-jest \
  eslint-plugin-jsx-a11y \
  eslint-plugin-prettier \
  eslint-plugin-react \
  eslint-plugin-react-hooks \
  husky \
  lint-staged \
  prettier
$ touch \
  .eslintignore \
  .eslintrc.js \
  .prettierrc.js \
  husky.config.js \
  lint-staged.config.js

The .eslintignore file will make sure we include files and folders that are ignored by default (using the !) and exclude files and folders that we don't care about linting.

!.eslintrc.js
!.prettierrc.js
!.storybook/
dist/
docs/
examples/

The .eslintrc.js file is something you and your team will need to figure out for yourselves, but here's where I stand on the issues:

module.exports = {
  env: {
    browser: true,
    es6: true,
    jest: true,
    node: true,
  },
  extends: [
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier/@typescript-eslint',
    'plugin:prettier/recommended',
    'plugin:jsx-a11y/recommended',
  ],
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: 'module',
  },
  parser: '@typescript-eslint/parser',
  plugins: ['jsx-a11y', 'react', 'react-hooks', '@typescript-eslint'],
  rules: {
    '@typescript-eslint/no-unused-vars': 'error',
    'jsx-quotes': ['error', 'prefer-double'],
    'jsx-a11y/no-onchange': 'off', // https://github.com/evcohen/eslint-plugin-jsx-a11y/issues/398
    'no-trailing-spaces': 'error',
    'object-curly-spacing': ['error', 'always'],
    quotes: ['error', 'single', { allowTemplateLiterals: true }],
    'react-hooks/exhaustive-deps': 'error',
    'react-hooks/rules-of-hooks': 'error',
    'react/prop-types': 'off',
    semi: ['error', 'never'],
  },
  settings: {
    react: {
      version: 'detect',
    },
  },
  overrides: [
    {
      files: ['*.js', '*.jsx'],
      rules: {
        '@typescript-eslint/explicit-function-return-type': 'off',
        '@typescript-eslint/no-var-requires': 'off',
      },
    },
  ],
}

The .prettierrc.js file defines your prettier configuration:

module.exports = {
  semi: false,
  singleQuote: true,
}

We're almost done with the linting! There are two files left.

For our husky.config.js file, we'll set it up to run lint-staged before we push our code to our repository:

module.exports = {
  hooks: {
    'pre-push': 'lint-staged',
  },
}

And for lint-staged.config.js, we'll specify that we want to run eslint --fix on our staged files:

module.exports = {
  '*': ['eslint --fix'],
}

Now that we've got this all in place, we can update our package.json's script object to include a lint command:

"scripts": {
  "lint": "eslint ."
},

You can test this by running:

$ npm run lint

Testing Setup

We're going to use Jest and @testing-library/react to handle running our tests and testing our component code, so let's install those tools and their companion TypeScript libraries. We'll also install axe-core to handle some automated accessibility testing.

$ npm install --save-dev --save-exact \
  @testing-library/jest-dom \
  @testing-library/react \
  @types/jest \
  axe-core \
  jest \
  ts-jest
$ touch jest.config.js testSetup.ts

Our jest.config.js collects coverage from the right places, ignores distribution and example directories, requires the testSetup.ts file, and sets us up to use TypeScript in our tests.

module.exports = {
  clearMocks: true,
  collectCoverage: true,
  collectCoverageFrom: ['<rootDir>/source/**/*.{ts,tsx}'],
  coveragePathIgnorePatterns: [
    '/node_modules/',
    '<rootDir>/source/@types',
    'stories',
  ],
  moduleNameMapper: {},
  preset: 'ts-jest',
  setupFilesAfterEnv: ['<rootDir>/testSetup.ts'],
  testPathIgnorePatterns: ['dist/', 'examples/'],
  verbose: true,
}

And here is our testSetup.ts file that you can use to provide global testing tools, patch JSDOM, and more:

import '@testing-library/jest-dom/extend-expect'

All we do in testSetup.ts is add a lot of custom matchers to the expect function from jest via @testing-library/jest-dom.

While we're on the testing subject, we should also update our package.json's scripts object to include a test command:

"scripts": {
  // ...
  "test": "jest"
},

We don't have any test files yet, but you can confirm everything is set up correctly by running

$ npm run test

Storybook Setup

Storybook is a great way to not only share examples of your components but also get instant feedback while developing them, as well. It also comes with a great set of official addons.

Let's install Storybook for React with TypeScript, and let's also add the addons for accessibility and knobs:

$ npm install --save-dev --save-exact \
  @storybook/addon-a11y \
  @storybook/addon-knobs \
  @storybook/preset-typescript \
  @storybook/react \
  babel-loader \
  ts-loader
$ mkdir .storybook
$ touch .storybook/main.js

The .storybook/main.js file is where we can specify our Storybook options:

module.exports = {
  addons: [
    '@storybook/addon-a11y',
    '@storybook/addon-knobs',
    '@storybook/preset-typescript',
  ],
  stories: ['../source/**/*/stories.tsx'],
}

An Example Component

For our example component, we are going to make a circle with SVG. With only this simple component, we will cover the following aspects of component development:

TypeScript interfaces for required and optional React props
Component CSS
Testing (regular, snapshot, and accessibility)
Storybook examples

Let's create the files we know we're going to need:

$ mkdir source/Circle
$ touch source/Circle/index.tsx \
  source/Circle/stories.tsx \
  source/Circle/styles.css \
  source/Circle/test.tsx

Component File

import React, { FC } from 'react'

// className, desc, and fill are optional,
// whereas title and size are required
interface Props {
  className?: string
  desc?: string
  fill?: string
  size: number
  title: string
}

// we provide our Props interface to the
// function component type
const Circle: FC<Props> = ({
  className = 'rl-circle',
  desc,
  fill,
  size,
  title,
}) => (
  <svg
    className={className}
    height={size}
    fill={fill}
    role="img"
    viewBox="0 0 100 100"
    width={size}
    xmlns="http://www.w3.org/2000/svg"
  >
    <title>{title}</title>
    {desc && <desc>{desc}</desc>}
    <circle cx="50" cy="50" r="50" />
  </svg>
)

export default Circle

In this component file, we define the parameters that we're willing to work with, provide a fallback in the case of className, and make a regular old component.

This file should be pretty straightforward, so let's move on to the CSS!

Component CSS

This is a real easy one.

.rl-circle { margin: 1em; }

The rl is short for "react library", and I made it up. The CSS that we are creating needs to be made unique, and prefixing your classes is the simplest way of doing that.

Component Tests

It's time to write some tests! We're going to make explicit expectations and do some snapshot tests so that everybody is happy.

import React from 'react'
import { render } from '@testing-library/react'
import Circle from './index'

test('with all props', () => {
  const { asFragment, container, getByText } = render(
    <Circle
      className="class-override"
      desc="A blue circle"
      fill="#30336b"
      size={200}
      title="Water planet"
    />
  )
  const svgEl = container.querySelector('svg')
  const titleEl = getByText('Water planet')
  const descEl = getByText('A blue circle')

  expect(svgEl).toHaveAttribute('height', '200')
  expect(svgEl).toHaveAttribute('width', '200')
  expect(titleEl).toBeInTheDocument()
  expect(descEl).toBeInTheDocument()
  expect(asFragment()).toMatchSnapshot()
})

test('with only title & size', () => {
  const { asFragment, container, getByText } = render(
    <Circle title="Water planet" size={200} />
  )
  const svgEl = container.querySelector('svg')
  const titleEl = getByText('Water planet')
  const descEl = container.querySelector('desc')

  expect(svgEl).toHaveAttribute('height', '200')
  expect(svgEl).toHaveAttribute('width', '200')
  expect(titleEl).toBeInTheDocument()
  expect(descEl).not.toBeInTheDocument()
  expect(asFragment()).toMatchSnapshot()
})

These first tests provide different sets of props and test various aspects of our component based on given props' inclusion.

Next, we can use the axe-core tool to try our hand at accessibility testing:

import axe from 'axe-core'

// ...

test('is accessible with title, desc, size', (done) => {
  const { container } = render(
    <Circle desc="A blue circle" size={200} title="Water planet" />
  )

  axe.run(container, {}, (err, result) => {
    expect(err).toEqual(null)
    expect(result.violations.length).toEqual(0)
    done()
  })
})

test('is inaccessible without title', (done) => {
  const { container } = render(
    <Circle desc="A blue circle" title="Water circle" size={200} />
  )

  // do something very wrong to prove a11y testing works
  container.querySelector('title')?.remove()

  axe.run(container, {}, (err, result) => {
    expect(err).toEqual(null)
    expect(result.violations[0].id).toEqual('svg-img-alt')
    done()
  })
})

While the first test should be clear, the second test almost seems pointless (hint: it is). I am including it here to demonstrate what a failing accessibility scenario might look like. In reality, the first test in this group pointed out the error in the second test, for I was originally not requiring title, but I was giving the SVG role="img". This is a no-no if there is no aria-label, aria-labelledby, nor <title> to supply the SVG with any textual meaning.

Testing is easy if you keep things simple, and automated accessibility testing is even easier than that, for all you need to do is provide DOM elements.

Component Stories

I find it very difficult to do test driven development when developing components, for it is an exploratory, creative experience for me. Instant feedback makes it easy to run through all my bad ideas (there are many!) and eventually land on some good ones. Storybook stories can help us do that, so let's make our first story in source/Circle/stories.tsx.

import React from 'react'
import { storiesOf } from '@storybook/react'
import { withA11y } from '@storybook/addon-a11y'
import { color, number, text, withKnobs } from '@storybook/addon-knobs'

// import our component and styles from
// the distribution (build) output
import { Circle } from '../../dist/esm'
import '../../dist/css/Circle/styles.css'

// group our stories under "Circle"
const stories = storiesOf('Circle', module)

// enable the accessibility & knobs addons
stories.addDecorator(withA11y)
stories.addDecorator(withKnobs)

// add a new story and use the
// knobs tools to provide named
// defaults that you can alter
// in the Storybook interface
stories.add('default', () => (
  <Circle
    desc={text('desc', 'A blue circle')}
    fill={color('fill', '#7ed6df')}
    size={number('size', 200)}
    title={text('title', 'Abstract water planet')}
  />
))

stories.add('another scenario...', () => (
  <Circle {/* other example props here */} />
))

Each component gets its own stories.tsx file, so there's no need to worry about them getting out of hand with all the different components in your library. Add as many different stories for your components as you like! Our Storybook config will collect them all for you into a single place.

Building Our TypeScript

We've already created a tsconfig.base.json and tsconfig.json file, and now it's time to add ones for CommonJS (CJS), ESModules (ESM), and Universal Module Definitions (UMD). We will then add some NPM scripts to build out TypeScript for us.

$ touch tsconfig.cjs.json tsconfig.esm.json tsconfig.umd.json

// tsconfig.cjs.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "dist/cjs/"
  },
  "include": ["source/index.ts"]
}

// tsconfig.esm.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "module": "esNext",
    "outDir": "dist/esm/"
  },
  "include": ["source/index.ts"]
}

// tsconfig.umd.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "module": "umd",
    "outDir": "dist/umd/"
  },
  "include": ["source/index.ts"]
}

Each of these specify where to find the source, what type of module to output, and where to put the resulting compiled code. If you want your code to be compiled to the output, make sure it is either included in the include field or is required by something that is.

In our package.json, let's add some scripts that make use of these configs:

"scripts": {
  "build:js:cjs": "tsc -p tsconfig.cjs.json",
  "build:js:esm": "tsc -p tsconfig.esm.json",
  "build:js:umd": "tsc -p tsconfig.umd.json",
  // ...
},

Easy! If you are guessing that we might want to run these all together in a build:js command, there are two ways to do that (one verbose and one less so).

Our first attempt:

"scripts": {
  "build:js": "npm run build:js:cjs && npm run build:js:esm && npm run build:js:umd",
  // ...
},

Not bad, but we can use the npm-run-all tool to not only write a more succinct script but also run these in parallel!

$ npm install --save-dev --save-exact npm-run-all

"scripts": {
  "build:js": "run-p build:js:cjs build:js:esm build:js:umd",
  // ...
},

The npm-run-all tool gives us run-p for running scripts in parallel and run-s for running them synchronously.

Watching for changes is also very simple:

"scripts": {
  // ...
  "build:js:esm:watch": "tsc -p tsconfig.esm.json -w",
  // ...
},

While we're here, let's go ahead and add a cleaning script for our dist/ directory:

"scripts": {
  // ...
  "clean": "clean:dist", // we'll add more here shortly
  "clean:dist": "rm -rf dist",
  // ...
},

Now that we can do some cleaning and building, let's create a single build script that we can continue adding build steps to as we go:

"scripts": {
  "build": "run-s clean build:js", // we'll add more here shortly
  // ...
}

Give it all whirl, if you like:

$ npm run build

You should see the following tree structure for your dist/ folder:

.
└── dist
    └── cjs
        └── Circle
            ├── index.d.js
            └── index.js
        ├── index.d.js
        └── index.js
    └── esm
        └── Circle
            ├── index.d.js
            └── index.js
        ├── index.d.js
        └── index.js
    └── umd
        └── Circle
            ├── index.d.js
            └── index.js
        ├── index.d.js
        └── index.js

We're getting places! We have JS, and now we need our CSS.

Building Our CSS

For our styles, we have two goals:

output each component's styles in a component CSS folder like dist/css/Circle/styles.css
output a combination of each component's styles in a single file in dist/css/styles.css

To achieve this, we're going to write a short bash script, and we're going to place it in scripts/buildCSS.

$ mkdir scripts
$ touch scripts/buildCSS
$ chmod +x scripts/buildCSS

And in scripts/buildCSS:

#!/bin/bash
set -euo pipefail

function copy_css {
  local dir=$(dirname $0)
  local component=$(basename $dir)
  local dist_css=$PWD/dist/css

  # concatenate component CSS to main CSS file
  mkdir -p $dist_css
  cat $0 >> $dist_css/styles.css

  # copy component CSS to component folder
  mkdir -p $dist_css/$component/
  cp $0 $dist_css/$component/
}

export -f copy_css

function build {
  find $PWD/source \
    -name '*.css' \
    -exec /bin/bash -c 'copy_css $0' {} \;
}

build

We lean on some coreutils here to solve our problems for us. The last line of our script, build, calls the function of the same name that looks inside the source directory for all CSS files and tells the bash program to run copy_css with the path to the CSS file. There's a catch, though: bash is going to run in a subshell, so we need to make sure our copy_css function is exported and available by export -f copy_css.

For the copy_css function, it's much simpler than it looks! Here are the
steps:

mkdir -p $dist_css creates our output directory, dist/css.
cat $0 >> $dist_css/styles.css concatenates all the lines of our source CSS file and appends them to dist/css/styles.css.
mkdir -p $dist_css/$component/ creates a component CSS folder like dist/css/Circle/. We derive the $component variable by getting the basename of the dirname of our full CSS file path. For example, /Users/myuser/projects/example-component-library/source/Circle/styles.css has a dirname of /Users/rpearce/projects/example-component-library/source/Circle, and that has a basename of Circle! Using that deduction, we can derive what component we're working with and create that output directory simply by finding a CSS file.
cp $0 $dist_css/$component/ copies the source component CSS file to the output component directory; that's it!

If you have a different CSS setup, you'll need to adjust this build script accordingly.

Now that we have our buildCSS script, we can add an NPM script to handle building this for us and add that to our build script:

"scripts": {
  "build": "run-s clean build:js build:css",
  "build:css": "./scripts/buildCSS",
  // ...
},

Similarly to our build:js:esm:watch command, how might we watch for CSS changes and run our script in a build:css:watch command? Luckily, there's a tool that can help us with that: chokidar.

$ npm install --save-dev --save-exact chokidar

"scripts": {
  // ...
  "build:css:watch": "chokidar \"source/**/*.css\" -c \"./scripts/buildCSS\"",
  // ...
},

Building Our Stories

To develop our components and get instant feedback in our Storybook examples, we're going to need to run a few things at once to get it all to work together.

First, let's add a line to our package.json's scripts object called
storybook:

"scripts": {
  // ...
  "storybook": "start-storybook -p 6006"
},

Next, let's add a start command that, in this sequence,

cleans the dist/ directory
builds only the ESModule JS output
builds the CSS

and then, in parallel,

watches the JS for changes and rebuilds the ESModule output
watches the CSS for changes and rebuilds the CSS
runs storybook, which watches for changes to the prior two items, for it will detect changes to its imports from the dist/ folder

"scripts": {
  // ...
  "start": "run-s clean:dist build:js:esm build:css && run-p build:js:esm:watch build:css:watch storybook",
  // ...
},

If you want to break those up into different scripts to make it more legible, here's a way to do that:

"scripts": {
  // ...
  "start": "run-s start:init start:run",
  "start:init": "run-s clean:dist build:js:esm build:css",
  "start:run": "run-p build:js:esm:watch build:css:watch storybook",
  // ...
},

You can then run this from the command line, and it should automatically open your web browser and take you to http://localhost:6006.

$ npm run start

Your Storybook library should have your component, and you can adjust the component knobs in one of the sidebars, and you can also see the accessibility audit located in the tab next to the knobs. Note: no amount of automated testing can guarantee accessibility, but it can help you catch silly mistakes.

With all these pieces in place, you can now develop your components and get instante feedback in the browser using the same code that you would provide to a consumer of your package!

Did you know that you can also build static HTML, CSS, and JavaScript files and serve that up through something like GitHub Pages? We can update our package.json scripts to include scripts for building our Storybook output to the docs/ folder and for cleaning the docs/ folder, as well.

"scripts": {
  // ...
  "build:docs": "build-storybook -o docs",
  "clean:docs": "rm -rf docs"
  "storybook": "start-storybook -p 6006"
},

The clean:docs script, if ran first, will guarantee that we have fresh output in our docs/ folder. Let's give it a go:

$ npm run clean:docs && npm run build:docs

Since we can now clean and build our Storybook folder, we can update our build and clean scripts accordingly:

"scripts": {
  "build": "run-s clean build:js build:css build:docs",
  // ...
  "clean": "run-p clean:dist clean:docs",
  // ...
},

Continuous Integration Notes

When you set up a continuous integration (CI) tool for this project, it will be tempting to tell it to simply run $ npm run build; however, this will not include your linting and testing scripts, and you could potentially have a green light from CI when really you have problems!

While you could always run your linting and testing scripts inside of build ( this can get tedious) or multiple scripts from your CI configuration, let's instead add another script named ci to handle this for us:

"scripts": {
  // ...
  "ci": "run-p lint build test",
  // ...
},

No worries! Now we can use $ npm run ci in our CI configuration.

Publishing Notes

I recommend adding a prepublishOnly script that ensures your linter and tests pass before trying to build your component output:

"scripts": {
  // ...
  "prepublishOnly": "run-p lint test && run-p build:js build:css",
  // ...
},

Also, if you want this to be a private repository, make sure you add "private": true to your package.json before publishing.

Wrapping Up

Thank you for reading this, and I hope this helps you create an awesome, accessible component library.

Robert

Catch Low-Hanging Accessibility Fruit with axe-core

Robert Pearce — Fri, 21 Feb 2020 16:05:48 +0000

Deque Systems, in addition to having an accessibility-testing browser plugin, has an open source package, axe-core, that can help you determine if HTML contains obvious accessibility issues.

That tool can be used on its own in your tests, or you can turn it into a Promise and use it like this!

import axe from 'axe-core'

const isA11y = html =>
  new Promise((resolve, reject) => {
    axe.run(html, {}, (err, result={}) => {
      const { violations=[] } = result

      if (err) {
        reject(err)
      } else if (violations.length > 0) {
        reject(violations)
      } else {
        // Uncomment to view incomplete/unavailable tests & why
        //console.log(result.incomplete)
        resolve(true)
      }
    })
  })

test('bad form', async () => {
  const wrap = document.createElement('div')
  wrap.innerHTML = `
    <form>
      <div>Enter your name</div>
      <input type="text" />
      <button type="submit">Submit</button>
    </form>
  `
  document.body.appendChild(wrap)

  expect(await isA11y(wrap)).toEqual(true)
})
// Failed: Array [
//   Object {
//     "description": "Ensures every form element has a label",
//     "help": "Form elements must have labels",
//     "helpUrl": "https://dequeuniversity.com/rules/axe/3.5/label?application=axeAPI",
//     "id": "label",
//     "impact": "critical",
//     "nodes": Array [
//       [Object],
//     ],
//     "tags": Array [
//       "cat.forms",
//       "wcag2a",
//       "wcag332",
//       "wcag131",
//       "section508",
//       "section508.22.n"
//     ],
//   }
//  ]

It can detect all sorts of accessibility issues, so long as the environment in which it's being tested supports the browser features used in axe-core's tests. For example, jsdom, which jest uses as its browser mocking engine, only recently added some support for Range, it seems there are still some aspects missing, and this prevents axe-core from being able to test things like the color contrast accessibility of text color on certain backgrounds.

That said, the sheer number of issues that can be caught with this tool is staggering. If you work with tools like React and combine this with Deque's react-axe tool and eslint-plugin-jsx-a11y, you are sure to catch heaps of low-hanging fruit.

Here is an example in a real OSS project of mine that uses this axe-core technique with @testing-library/react: https://github.com/rpearce/react-medium-image-zoom/blob/6721f87370d968361d9d0d14cd30d752832877d1/__tests__/Uncontrolled.js#L27.

What are you waiting for?

This is also posted on https://robertwpearce.com/catch-low-hanging-accessibility-fruit-with-axe-core.html.

Writing a Functional Programming-Style map Function

Robert Pearce — Thu, 20 Feb 2020 15:11:17 +0000

Many thanks to Helen Durrant for reviewing this post and offering stellar suggestions. Originally posted on https://robertwpearce.com/javascript-writing-a-functional-programming-style-map-function.html.

In this post, we will write a functional programming-style implementation of JavaScript's map function that not only works with Array but any data structure that implements a map method. Such data structures are known as Functors. Some examples of Functors are the algebraic data types¹ Maybe and Async (prior knowledge of them is not required, and out of the two, we'll only use Maybe).

By the end of this post, you will:

know how to implement a generic map function that includes functions for mapping Arrays, Objects, and Functors
understand how to use map in a variety of scenarios
know how to write a simple compose function and use composition
know how to reliably test values for their types
have received a small introduction to algebraic data types via the crocks library

This is a big post, so buckle up! If you want to see the final product, check out this CodeSandbox: https://codesandbox.io/s/bitter-grass-tknwb.

Note: if you're not familiar with Array.prototype.map already, check out my video on Using JavaScript's Array.prototype.map Method or my post on JavaScript: Understand Array.prototype.map by Reimplementing It.

We will use the implementation of the map function in crocks as our template, so if you want to skip this article entirely, you can go and view its source.

Overview

The Goal: map All the Things
Defining Our map Function
map an Array
map an Object
map a Function
map a Functor
throwing Out Bad Data

The Goal: `map` All the Things

Today we are going to write a map function that does the following:

accepts a transformation function that takes in some argument of type a and transforms it into a value of type b; i.e., (a -> b)
accepts and handles any of the following data types:
- Array
- Object
- Function
- Functors (e.g., Maybe)

Sounds easy, right? We'll see!

Defining Our `map` Function

There are some things we already know about our map function:

it's called map (yay! nailed it!)
it takes a function (fn) and then some datum (m²)³
it returns the datum as transformed by said function

Let's sketch it out:

const map = (fn, m) => {
  // ???
}

Okay, it's a start. This could conceivably be used like this:

map(x => x.id, [{ id: 1 }, { id: 2 }])     // [1, 2]
map(x => x.id, [{ id: 'a' }, { id: 'b' }]) // ['a', 'b']

Note the repetition of the x => x.id. Let's try pulling it out into a
variable:

const propId = x => x.id
map(propId, [{ id: 1 }, { id: 2 }])     // [1, 2]
map(propId, [{ id: 'a' }, { id: 'b' }]) // ['a', 'b']

Alas, that's not much better – now we're just repeating the variable!

Instead, what if we could store our combination of function and map in a variable and then use that to call with our different data? By partially applying the function to map, we can!

const mapId = map.bind(null, x => x.id)
mapId([{ id: 1 }, { id: 2 }])     // [1, 2]
mapId([{ id: 'a' }, { id: 'b' }]) // ['a', 'b']

Nice! Now, let's go back to our sketch. Let's turn our binary function (which takes two parameters) to instead be a series of unary functions (which take one parameter⁴).

const map = fn => m => {
  // ???
}

Wow, that was easy. By default, languages like Haskell and Elm automatically curry all of their function parameters. There are ways to automate that in JavaScript, but for today, we will manually curry functions by using arrow functions to simulate it: const sum = a => b => a + b, for example.

Lastly, on the function definition side, it would be helpful for readers of our code to understand more about the intended types. In lieu of JavaScript not having a static type checker and me not knowing TypeScript yet, we'll do this using a Haskell-style pseudo-type signature:

map :: Functor f => (a -> b) -> f a -> f b

And we can place that as a comment above our function:

// map :: Functor f => (a -> b) -> f a -> f b
const map = fn => m => {
  // ???
}

Woah, woah, woah! What's all this? Let's break it down.

map :: Functor f => (a -> b) -> f a -> f b
--  |     |            |     |   |      |
--  1     2            3     4   5      6

Can be read, "has the type of"
Anything after :: and before => in a signature is a class constraint. This says we're going to use something in the type signature that obeys the Functor Laws⁵, identity and composition. The lowercase f represents what the Functor will be in the signature.
Our mapping function; e.g., x => x.id, like we did above.
-> Arrows are used in type signatures to say "then return...". In our map signature, we say, "We accept a function from a to b then return a function that accepts f of a and then return f of b". If we were summing three numbers, sum3 :: Number -> Number -> Number -> Number, this would read, "sum3 has the type of an expression that accepts a Number that returns a function that accepts a Number then returns a function that accepts a Number and then returns a Number."
f a says that a Functor, f, wraps some other type, a. A concrete example of this is [Number], which is a list (or Array) of Numbers.
f b says that a Functor, f, wraps some other type, b. Why isn't it a? This signifies that when we take in the Functor of any type a, it's totally cool if you want to change the return type inside the Functor. For example, when we take [{ id: 'a' }, { id: 'b' }] and use map to turn that into ['a', 'b'], we're taking [Object] (a list of Objects) and turning that into [String] (a list of Strings).

All together now! "map has the type of an expression where f is a Functor, and it accepts a function from a to b, then returns a function that accepts f of a, and then returns f of b."

`map` an `Array`

Let's map an Array!

Remember our Functor class constraint?

map :: Functor f => (a -> b) -> f a -> f b

Guess what? Array is a Functors! How? It adheres to the laws of identity and composition:

// identity
[1,2,3].map(x => x) // [1,2,3]

// composition
const add10 = x => x + 10
const mult2 = x => x * 2
[1,2,3].map(add10).map(mult2)     // [ 22, 24, 26 ]
// is equivalent to...
[1,2,3].map(x => mult2(add10(x))) // [ 22, 24, 26 ]

// another example of the composition law
const compose = (f, g) => x => f(g(x))
mult2(add10(2)) === compose(mult2, add10)(2) // true

// and applied back to our prior example
[1,2,3].map(add10).map(mult2)      // [ 22, 24, 26 ]
[1,2,3].map(x => mult2(add10(x)))  // [ 22, 24, 26 ]
[1,2,3].map(compose(mult2, add10)) // [ 22, 24, 26 ]

Through map, Array is a Functor. A way to quickly determine if something is a Functor is to ask, "Does it implement map / is it mappable?"

Since we know that Array is mappable, we can use our map function to check if the f a parameter is an Array and then use the build in Array.prototype.map function to get from a to b:

// map :: Functor f => (a -> b) -> f a -> f b
const map = fn => m => {
  if (isArray(m)) {
    return mapArray(fn, m)
  }
}

// isArray :: a -> Bool
const isArray = x => Array.isArray(x)

// mapArray :: ((a -> b), Array a) -> Array b
const mapArray = (fn, m) => m.map(x => fn(x))

Here, we use Array.isArray()⁶ to see if the argument, m, is an Array, then we call a function, mapArray, that handles the mapping of the Array.

You might be thinking: why m.map(x => fn(x)) and not m.map(fn)? As you might remember from my article on re-implementing Array.prototype.map, there are a few other arguments that the native implementation of map provide, as well as some potential changes to the this keyword in your callback function scope. Instead of allowing those to pass through, we simply take the first argument, the currently iterated value, and send that to the callback function⁷.

Now that we've seen the easy way to do map with Array, let's see what this would look like if we felt like implementing mapArray ourselves:

// mapArray :: ((a -> b), Array a) -> Array b
const mapArray = (fn, m) => {
  const newArray = []

  for (let i = 0; i < m.length; i++) {
    newArray[i] = fn(m[i])
  }

  return newArray
}

Not too shabby! All we do is create a new Array and set the results of calling the callback function with each item to its index in the new Array and then return that Array.

Do you think our map function can handle an Array of Arrays?

map(x => x * 2)([ [1,2], [3,4], [5,6] ])
// Array(3) [ NaN, NaN, NaN ]

While we can successfully iterate over the 3 items in the top-level Array, our callback function can't perform operations like [1,2] * 2! We need to do another map on the nested Arrays:

map(map(x => x * 2))([ [1,2], [3,4], [5,6] ])
// [ [2,4], [6,8], [10,12] ]

Well done! What else can you map? We're now going to leave charted waters and venture into the unknown.

`map` an `Object`

Let's say we have an i18n (short for "internationalization") object that we've been given that has a terribly annoying issue: every translation is prefixed and suffixed with an underscore (_)!

const i18n = {
  'en-US': {
    dayMode: '_Day mode_',
    greeting: '_Hello!_',
    nightMode: '_Night Mode_'
  },
  'es-ES': {
    dayMode: '_Modo día_',
    greeting: '_¡Hola!_'
    nightMode: '_Modo nocturno_'
  }
}

We could manually delete each one, or we could find and replace with our text editor, or we could write a for loop to do this, but because we're super awesome functional programmers, we'll try to map over the Object and write a function that removes the prefixed & suffixed underscores (...then we copy and paste that? work with me here!).

Before we can do this, we need to see what happens when we call .map() on an Object:

i18n['en-US'].map(x => x.slice(1))
// TypeError: i18n['en-US'].map is not a function

Oh no! If we can't even fix the en-US Object, how are we supposed to fix all of them? Let's update our map function to handle Objects.

// map :: Functor f => (a -> b) -> f a -> f b
const map = fn => m => {
  if (isArray(m)) {
    return mapArray(fn, m)
  }

  if (isObject(m)) {
    return mapObject(fn, m)
  }
}

// isObject :: a -> Bool
const isObject = x =>
  !!x && Object.prototype.toString.call(x) === '[object Object]'

// mapObject :: ((a -> b), { k: a }) -> { k: b }
const mapObject = (fn, m) => {
  const obj = {}

  for (const [k, v] of Object.entries(m)) {
    obj[k] = fn(v)
  }

  return obj
}

Here, we test if something is an object by using Object.prototype.toString and make sure to .call(x) instead of just .toString(x), for this reason:

Object.prototype.toString(null)
// "[object Object]"

Object.prototype.toString.call(null)
// "[object Null]"

Object.prototype.toString([])
// "[object Object]"

Object.prototype.toString.call([])
// "[object Array]"

Object.prototype.toString.call({})
// "[object Object]"

We then use our new mapObject function, whose signature is

mapObject :: ((a -> b), { k: a }) -> { k: b }

mapObject takes a function from a to b and an Object with a key(s) and some value(s), a, and returns an Object with a key(s) and some value(s) b. In short, it maps the values of an Object. Our mapObject function is nothing more than a for loop over each value returned from Object.entries()! It calls the callback function with each value and returns a new object with the same key and a new, updated value.

Let's try it out:

const i18n = {
  'en-US': {
    dayMode: '_Day mode_',
    greeting: '_Hello!_',
    nightMode: '_Night Mode_'
  },
  'es-ES': {
    dayMode: '_Modo día_',
    greeting: '_¡Hola!_'
    nightMode: '_Modo nocturno_'
  }
}
map(x => x.slice(1, -1))(i18n['en-US'])
// {
//   dayMode: 'Day mode',
//   greeting: 'Hello!',
//   nightMode: 'Night Mode'
// }

Okay – what about our entire i18n object?

map(map(x => x.slice(1, -1)))(i18n)
// {
//  'en-US': {
//    dayMode: 'Day mode',
//    greeting: 'Hello!',
//    nightMode: 'Night Mode'
//  },
//  'es-ES': {
//    dayMode: 'Modo día',
//    greeting: '¡Hola!',
//    nightMode: 'Modo nocturno'
//  }
// }

Since we're dealing with nested objects, we need to use map on an Object inside an Object. We pass a nested mapping function, and our little underscore problem is gone!

`map` a `Function`

Remember our functions mult2 and add10 from before?

const add10 = x => x + 10
const mult2 = x => x * 2

What would happen if we used those as the arguments to our map function and wanted them to be automatically composed together so that we can then provide a value later?

map(add10)(mult2)     // undefined
map(add10)(mult2)(12) // TypeError: map(...)(...) is not a function

Time for our map function to handle a Function as the second argument and compose the two functions together:

// map :: Functor f => (a -> b) -> f a -> f b
const map = fn => m => {
  if (isArray(m)) {
    return mapArray(fn, m)
  }

  if (isObject(m)) {
    return mapObj(fn, m)
  }

  if (isFunction(m)) {
    return compose(fn, m)
  }
}

// isFunction :: a -> Bool
const isFunction = x => typeof x === 'function'

// compose :: ((b -> c), (a -> b)) -> a -> c
const compose = (f, g) => x => f(g(x))

And when we run our previously failed code again,

map(add10)(mult2)     // function compose(x)
map(add10)(mult2)(12) // 44

we can see that calling map with two functions returns a composition of those two functions, and calling that result with a primitive value (12) gives us back our result, 44.

`map` a `Functor`

When we learned about mapping Arrays before, we learned that Arrays are Functors because they adhere to the laws of identity and composition; i.e., they are mappable.

There are all sorts of other data structures that implement a map method, just like Array.prototype does, and we want to be able to handle those, too!

We currently have all the tools required to implement map for Functors without even knowing how they might work! All we need to know is, "Does it implement map as a Function?" Let's see what we can come up with!

// map :: Functor f => (a -> b) -> f a -> f b
const map = fn => m => {
  if (isFunction(m)) {
    return compose(fn, m)
  }

  if (isArray(m)) {
    return mapArray(fn, m)
  }

  if (isFunctor(m)) {
    return mapFunctor(fn, m)
  }

  if (isObject(m)) {
    return mapObj(fn, m)
  }
}

// isFunction :: a -> Bool
const isFunction = x => typeof x === 'function'

// isFunctor :: a -> Bool
const isFunctor  = x => !!x && isFunction(x['map'])

// mapFunctor :: Functor f => ((a -> b), f a) -> f b
const mapFunctor = (fn, m) => m.map(fn)

That is surprisingly simple, isn't it? We use our isFunction check from before to test if m has a map property that is a Function, then we call map on m and pass it the callback Function in mapFunctor.

You might be thinking that mapArray and mapFunctor could use the same handler because Arrays are Functors, and you are correct; however, because of the extra implementation bits that come back from Array.prototype.map, we'll keep them separate and only call the callback to Array.prototype.map with the currently iterated item. Here's the difference:

// mapArray :: ((a -> b), Array a) -> Array b
const mapArray = (fn, m) => m.map(x => (fn(x))

// mapFunctor :: Functor f => ((a -> b), f a) -> f b
const mapFunctor = (fn, m) => m.map(fn)

If you don't care about this, it's totally acceptable to not include the Array bits at all and use the Functor map⁸ to handle the mapping of Arrays, since they're Functors.

To test our Functor mapping, we'll use crocks to provide us access to an algebraic data type called Maybe.

import { compose, option, prop } from 'crocks'

const company = {
  name: 'Pearce Software, LLC',
  locations: [
    'Charleston, SC, USA',
    'Auckland, NZ',
    'London, England, UK'
  ]
}

prop('foo', company)       // Nothing
prop('locations', company) // Just [String]

option([], prop('foo', company))
// []

option([], prop('locations', company))
// [
//   'Charleston, SC, USA',
//   'Auckland, NZ',
//   'London, England, UK'
// ]

const getLocations = compose(option([]), prop('locations'))
getLocations(company)
// [
//   'Charleston, SC, USA',
//   'Auckland, NZ',
//   'London, England, UK'
// ]

Pump the breaks! What's all this Just and Nothing stuff? We're not going to focus on Maybes today⁹, but the short version is that the locations property may or may not be present in the object, so we encapsulate that uncertainty inside of a Maybe algebraic data type via the prop function, and we provide a default value via the option function that the Maybe can fall back to in the event of not being able to find locations.

Why does this matter? We want to map a Maybe, and the prop function will give us access to one. Let's see what it looks like:

import { compose, option, prop } from 'crocks'

const upcase = x => x.toUpperCase()

const getLocations =
  compose(option([]), map(map(upcase)), prop('locations'))

getLocations({}) // []

getLocations(company)
// [
//   'CHARLESTON, SC, USA',
//   'AUCKLAND, NZ',
//   'LONDON, ENGLAND, UK'
// ]

Okay, cool! But why are we mapping twice?

When we work with algebraic data types like Maybe, instead of writing if (dataIsValid) doSomething, the map method on a Maybe gives us access to the value inside the Maybe (our locations), but it does so only if the data is available.

Once we have access to the locations, we then use map again to uppercase each location.

`throw`ing Out Bad Data

What happens if the arguments passed to map aren't a Function and a Functor?

map(null)([1,2,3])    // TypeError: fn is not a function
map(x => x * 2)(null) // undefined
map(null)(null)       // undefined

I think we can provide some more helpful messaging to guide users of our map tool on how to use it correctly.

// map :: Functor f => (a -> b) -> f a -> f b
const map = fn => m => {
  if (!isFunction(fn)) {
    throw new TypeError(`map: Please provide a Function for the first argument`)
  }

  // ...our other handlers...

  throw new TypeError(`map: Please provide a Functor or Object for the second argument`)
}

map(null)([1,2,3])    // TypeError: map: Please provide a Function for the first argument
map(x => x * 2)(null) // TypeError: map: Please provide a Functor or Object for the second argument
map(null)(null)       // TypeError: map: Please provide a Function for the first argument

Now, when we provide bad arguments, we're told exactly what we need to do.

Wrapping Up

Congratulations and thank you for making it to the end! If you want to play around with what we created, check out this CodeSandbox: https://codesandbox.io/s/bitter-grass-tknwb.

Here is our code from today in its entirety:

const { compose, option, prop } = require('crocks')

// map :: Functor f => (a -> b) -> f a -> f b
const map = fn => m => {
  if (!isFunction(fn)) {
    throw new TypeError(`map: Please provide a Function for the first argument`)
  }

  if (isFunction(m)) {
    return compose(fn, m)
  }

  if (isArray(m)) {
    return mapArray(fn, m)
  }

  if (isFunctor(m)) {
    return mapFunctor(fn, m)
  }

  if (isObject(m)) {
    return mapObj(fn, m)
  }

  throw new TypeError(`map: Please provide a Functor or Object for the second argument`)
}

// we're opting for crocks' compose, instead
// compose :: ((b -> c), (a -> b)) -> a -> c
// const compose = (f, g) => x => f(g(x))

// isArray :: a -> Bool
const isArray = x => Array.isArray(x)

// isFunction :: a -> Bool
const isFunction = x => typeof x === 'function'

// isFunctor :: a -> Bool
const isFunctor  = x => !!x && isFunction(x['map'])

// isObject :: a -> Bool
const isObject = x =>
  !!x && Object.prototype.toString.call(x) === '[object Object]'

// mapArray :: ((a -> b), Array a) -> Array b
const mapArray = (fn, m) => {
  const newArray = []

  for (let i = 0; i < m.length; i++) {
    newArray.push(fn(m[i]))
  }

  return newArray
}
// realistically, you should use this mapArray:
// const mapArray = (fn, m) => m.map(x => fn(x))

// mapObj :: (a -> b) -> { k: a } -> { k: b }
const mapObj = (fn, m) => {
  const obj = {}

  for (const [k, v] of Object.entries(m)) {
    obj[k] = fn(v)
  }

  return obj
}

// mapFunctor :: Functor f => ((a -> b), f a) -> f b
const mapFunctor = (fn, m) => m.map(fn)

Thank you for reading!

Robert

https://github.com/hemanth/functional-programming-jargon#algebraic-data-type ↩
m for Monoid ↩
Wondering why the data comes last? Check out Brian Lonsdorf's "Hey Underscore, You're Doing It Wrong!" talk. The tl;dr is that you should arrange your arguments from least likely to change to most likely to change in order to pave the way for partial application and greater code reuse. ↩
https://github.com/hemanth/functional-programming-jargon#arity ↩
https://github.com/hemanth/functional-programming-jargon#functor ↩
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray ↩
Check out ramda.js' addIndex function to see a different pattern for working with indices and Arrays. ↩
Functor map is also known as fmap. ↩
If you're an egghead.io subscriber, Andy Van Slaars has a great course, Safer JavaScript with the Maybe Type, or you can check out a Haskell article on The Functor class. ↩

Understand Array.prototype.map by Reimplementing It

Robert Pearce — Mon, 27 Jan 2020 12:56:27 +0000

Also published at https://robertwpearce.com/javascript-understand-array-prototype-map-by-reimplementing-it.html

In this post, we will reimplement JavaScript's Array.prototype.map function in order to not only understand map better but also to get an idea of how to implement instance methods on Array.prototype.

If you'd prefer to see a ~5 minute recording of what we'll do in this post, you can watch the video below; otherwise, carry on!

Initial Example: Use `map` to Convert Film Data to HTML Strings

First, we will start with some code that will demonstrate one way to take an array of films and output certain HTML strings.

Here is the films array:

// films :: [Film]
const films = [
  { title: `Pulp Fiction`, score: 8.9 },
  { title: `Forrest Gump`, score: 8.8 },
  { title: `Interstellar`, score: 8.6 },
  { title: `The Prestige`, score: 8.5 }
]

and here is the output we are going for:

[
  '<li class="film">#1 Pulp Fiction: <b>8.9</b></li>',
  '<li class="film">#2 Forrest Gump: <b>8.8</b></li>',
  '<li class="film">#3 Interstellar: <b>8.6</b></li>',
  '<li class="film film--last">#4 The Prestige: <b>8.5</b></li>'
]

Let's take a closer look at that output. We can see that the following data needs to be included for each item:

position in the list (#3)
title (Interstellar)
score (8.6)
CSS class of film, unless it is the last item, in which case it gets film and film--last

Here is the (somewhat unusual) implementation we will use today in order to later test that we successfully reimplemented Array.prototype.map:

// filmToHtml :: (Film, Index, Films) -> HtmlString
function filmToHtml(film, i, films) {
  return this.format({
    index: i + 1,
    isLast: i === films.length - 1,
    score: film.score,
    title: film.title,
  })
}

function format({ index, isLast, score, title }) {
  const cn = isLast ? `film film--last` : `film`
  return `<li class="${cn}">#${index} ${title}: <b>${score}</b></li>`
}

console.log(
  films.map(filmToHtml, { format })
)
// [
//   '<li class="film">#1 Pulp Fiction: <b>8.9</b></li>',
//   '<li class="film">#2 Forrest Gump: <b>8.8</b></li>',
//   '<li class="film">#3 Interstellar: <b>8.6</b></li>',
//   '<li class="film film--last">#4 The Prestige: <b>8.5</b></li>'
// ]

This is probably two-to-three times more complicated than it needs to be, but it is a sufficient example for today, for we make use of all of
Array.prototype.map's features.

Note: it's rare to use the second argument to map, but we are doing so today in order to test our implementation.

So what is going on here?

The map method iterates over each film and calls filmToHtml with a few arguments:

the film object
the film's index in the array
the films array

It also calls the filmToHtml function with an optional this scope. To
demonstrate how this works, we pass an object with the method format that filmToHtml then accesses via this.format. The format function then receives some data points and ultimately returns to us the <li>...</li> HTML for each film.

Defining Our Own `map` Method, `mappy`

If we want to write a new method that can be called on our films Array instance, we add it to the Array.prototype like this:

Array.prototype.mappy = function mappy(/* ??? */) {
  // our implementation will go here
}

Since a method is a function defined on an object, we know we are working with a function, but what arguments does our function accept?

What Is `map`'s Syntax?

As hinted at in a prior section, if we look at MDN's Array.prototype.map
syntax documentation, we can see that we need:

a callback that gets called with an optional scope and 3 arguments:
1. the currently iterated item
2. the current item's array index (an integer)
3. the source array that map is called upon
an optional value to use as this when calling the callback

Filling In The Argument Blanks

Let's give our mappy method a callback parameter, as well as an optional thisArg, which we'll simply name _this.

Array.prototype.mappy = function mappy(callback, _this) {

  // Let's then have it return our array instance
  // by returning the special `this` keyword.
  return this
}

console.log(
  films.map(filmToHtml, { format })
)
// [
//  { title: `Pulp Fiction`, score: 8.9 },
//  { title: `Forrest Gump`, score: 8.8 },
//  { title: `Interstellar`, score: 8.6 },
//  { title: `The Prestige`, score: 8.5 }
// ]

Since our mappy method, like map, will not alter the original array, we know we'll need to return a new array, so let's do that and return the empty array:

Array.prototype.mappy = function mappy(callback, _this) {
  const newArray = []
  return newArray
}

console.log(
  films.map(filmToHtml, { format })
)
// []

The Implementation

Now that we have a newArray, know we can work with this, have a callback to call and a _this scope to call the callback with, we can populate the newArray with the result of calling the callback function with each item in our array (and with the appropriate arguments, of course):

Array.prototype.mappy = function mappy(callback, _this) {
  const newArray = []

  // We'll use a for loop to iterate over
  // each item in our list,
  for (let i = 0; i < this.length; i++) {
    // and then at the end of our `newArray`
    // we'll append the result of calling
    // the callback function with the optional
    // scope and its 3 arguments:
    //   1. the item,
    //   2. the current item's index in the array,
    //   3. and lastly the original list, itself.
    newArray.push(
      callback.call(_this, this[i], i, this)
    )
  }

  // Ultimately, we return the `newArray`
  // containing our transformed items.
  return newArray
}

// And when we log out the result,
// we can see our `filmToHtml` function
// works as expected.
console.log(
  films.map(filmToHtml, { format })
)
// [
//   '<li class="film">#1 Pulp Fiction: <b>8.9</b></li>',
//   '<li class="film">#2 Forrest Gump: <b>8.8</b></li>',
//   '<li class="film">#3 Interstellar: <b>8.6</b></li>',
//   '<li class="film film--last">#4 The Prestige: <b>8.5</b></li>'
// ]

Providing Useful Error Messaging

What happens if someone tries to use our mappy method but doesn't provide a callback function? For example:

films.mappy(123)
// TypeError: callback.call is not a function

films.map(123)
// TypeError: 123 is not a function

Unfortunately, our mappy method doesn't take this scenario into account! But the map method's error messaging isn't totally clear at a glance, either, so let's try a different approach:

Array.prototype.mappy = function mappy(callback, _this) {
  if (typeof callback !== 'function') {
    throw new TypeError(
      'Array.prototype.mappy: ' +
      'A callback function was expected ' +
      'as the first argument, but we received ' +
      '`' + JSON.stringify(callback) + '`'
    )
  }

  const newArray = []

  for (let i = 0; i < this.length; i++) {
    newArray.push(
      callback.call(_this, this[i], i, this)
    )
  }

  return newArray
}

films.mappy(123)
// TypeError:
//   Array.prototype.mappy: A callback function was
//   expected as the first argument, but we received `123`

films.mappy({ foo: 'bar' })
// TypeError:
//   Array.prototype.mappy: A callback function was
//   expected as the first argument, but we received `{"foo":"bar"}`

Wrapping Up

I hope this post has helped de-mystify how Array.prototype.map conceptually works under the hood! Next time, we'll look at how to implement map without polluting the Array.prototype, and we might even be able to use map on more data structures than just Array! Stay tuned.

Thank you for reading!
Robert Pearce

DEV Community: Robert Pearce

Working on the "Ramda Ramp-Up Guide"

Dear Dia11y: Decorative & functional images

Decorative images

Functional images

Future-proof two types of visually hidden content

Figure & Figcaption: Supporting IE11, JAWS, NVDA, & VO

Image with SVG source VoiceOver bug

Hello, accessibility world!

Hakyll Pt. 6 – Pure Builds With Nix

Overview

Steps to Build Our Hakyll Project With Nix

Understanding the release.nix File

Wrapping Up

Build Your Team an Accessible, Shareable Component Library

Overview

When Should I Make a Component Library and Why?

Scenario 1: Component Entropy

Scenario 2: Multiple Projects (or The Possibility of Multiple Projects)

Project API (Usage)

JS Imports

CSS Imports

Main Project Tools

Project Structure

Component Structure

Creating the Project

TypeScript Setup

Linting Setup

Testing Setup

Storybook Setup

An Example Component

Component File

Component CSS

Component Tests

Component Stories

Building Our TypeScript

Building Our CSS

Building Our Stories

Continuous Integration Notes

Publishing Notes

Wrapping Up

Catch Low-Hanging Accessibility Fruit with axe-core

Writing a Functional Programming-Style map Function

Overview

The Goal: map All the Things

Defining Our map Function

map an Array

map an Object

map a Function

map a Functor

throwing Out Bad Data

Wrapping Up

Understand Array.prototype.map by Reimplementing It

Initial Example: Use map to Convert Film Data to HTML Strings

Defining Our Own map Method, mappy

What Is map's Syntax?

Filling In The Argument Blanks

The Implementation

Providing Useful Error Messaging

Wrapping Up

Understanding the `release.nix` File

The Goal: `map` All the Things

Defining Our `map` Function

`map` an `Array`

`map` an `Object`

`map` a `Function`

`map` a `Functor`

`throw`ing Out Bad Data

Initial Example: Use `map` to Convert Film Data to HTML Strings

Defining Our Own `map` Method, `mappy`

What Is `map`'s Syntax?