---
title: Building a Collapsible Web Component with Lit
description: Learn how to build a re-usable web component using slots
date: '2022-02-04'
image: 'colin-carter-w1g2o4J_4Dg-unsplash.webp'
---

Web components allow engineers to author re-usable, custom HTML elements which
can be used across platforms and frameworks. With a web component, an engineer
can build a custom component once, and re-use it within a React project, an
Angular project, or even a Ruby on Rails project.

I've written about
[implementing a collapsible component accessibly](/building-an-accessible-collapsible-element)
with vanilla HTML, so let's dive in with implementing this component using
[Lit](https://lit.dev).

## A simple example

For starters, let's take a look at a non-compound collapsible element:

<iframe src="https://stackblitz.com/edit/blogbuilding-a-compound-web-component-with-lit-01?ctl=1&embed=1&file=src/my-collapsible.ts&hideExplorer=1&hideNavigation=1&theme=dark"></iframe>

In this example, a single component controls the state of the element as well as
passed-in content. A `title` prop is used to handle the content of the
triggering element. Everything works! We can use our component like any other
HTML element, and it works as expected:

```html
<my-collapsible title="My Collapsible Element">
  <p>This content will show and hide dynamically</p>
</my-collapsible>
```

After patting ourselves on the back, we quickly receive a request for a new
feature - an implementing team now wants to add a custom icon inside the
triggering button. OK, that should be easy enough - we can just add a
`title-icon` prop:

```html
<my-collapsible
  title="My Collapsible Element"
  title-icon="<svg id='some-inline-svg'></svg>"
>
  <p>This content will show and hide dynamically</p>
</my-collapsible>
```

Nice! This solves our problem. Except, what do we do if an implementing team
wants to use a `.png` as an icon? Or maybe they want to pass in a custom web
component instead of an inline SVG? And what if they want to put the icon on
either side of the triggering element content? Or maybe they want to apply a
color to that particular icon instance? We could quickly end up creating a
component with a lot of hard-to-manage surface area:

```html

<my-collapsible
  title="My Collapsible Element"
  title-icon=""
  title-icon-image="/path/to/icon.png"
  title-icon-color="hotpink"
  icon-position="left"
>
  <p>This content will show and hide dynamically</p>
</my-collapsible>
```

## Slots to the rescue

Fortunately for us, the
[slot element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot)
allows us to expose multiple places within our component in which to render
child content, including arbitrary HTML or custom elements:

<iframe src="https://stackblitz.com/edit/blogbuilding-a-compound-web-component-with-lit-02?ctl=1&embed=1&file=src/my-collapsible.ts&hideExplorer=1"></iframe>

We have removed the `title` prop entirely, and have no need for any of the
icon-related props either, as an implementing team can slot in whatever content
they want via the `"title"` slot.

```html
<my-collapsible>
  <h2 slot="title">
    Click Me
    <svg id="this-is-my-inline-svg">...</svg>
  </h2>
  <p slot="content">This content will show and hide dynamically</p>
</my-collapsible>
```

### Wrapping Up

In this example, we implemented a simple, accessible collapsible custom element
using [Lit](https://lit.dev). By leveraging slots over props, we were able to
dramatically simplify the component API, reducing our maintenance overhead as
well as the risk of defects.

In a future post, I'll discuss a more complex pattern that can offer even more
control to implementing teams, all while maintaining a simple component API
using the
[compound component](https://kentcdodds.com/blog/compound-components-with-react-hooks)
pattern.

Learn how to build a re-usable web component using slots

Building a Collapsible Web Component with Lit

---
title: Building an Accessible, Re-usable Heading Component
description:
  Learn how to build a re-usable, accessible heading component with React.
date: '2021-04-22'
image: 'grant-ritchie-_-gToenDbXg-unsplash.webp'
---

[HTML headings](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
are not semantically complex elements though they are frequently used
inappropriately by both designers and engineers alike.

## Why Use Headings?

Each heading can be specificied with a level (1 through 6) and render text
content to the DOM. Generally, headings are used to group content in a
hierarchical fashion, much like a newspaper or magazine article.

```html
<h1>Man Lands on the Moon!</h1>

<h2>Who Landed?</h2>

<h3>The First Man on the Moon</h3>

<p>Neal Armstrong!</p>

<h3>The Rest</h3>

<p>Buzz Aldrin was also there!</p>

<h2>Were There Aliens?</h2>

<p>Sadly, no.</p>
```

In a traditional document layout, heading levels correspond naturally with the
flow of content. This document flow helps users quickly scan for content
visually and helps screen reader users navigate quickly around a page. WebAIM
wrote a
[great article on the subject](https://webaim.org/techniques/semanticstructure/#headings).

## Common Pitfalls

Both visual designers and developers make some common mistakes when using
headings in their work, largely stemming from the typical connection between
style and semantic meaning.

For better or for worse, modern web applications do not tend to contain long
blocks of structured content, making maintaining a strict heading hierachy more
difficult. Visual designers may, for example, hope to use a heading that _looks
like_ a level 5 heading when, according to the document hierarchy, a level 2
heading might be more appropriate.

Similarly, developers will often (inappropriately) leverage headings as a means
of styling. Without enough knowledge of the importance of the heading hierarchy
of a document, an engineer may reach for an `<h6 />` when a `<p />` with bold
styling was needed.

## Abstraction to the Rescue

Fortunately, building a re-usable `Heading` component abstraction can help
separate the visual presentation from the semantic meaning of a heading instance
without relying on manual, one-off styling.

### Styling

First, let's apply some styling to headings globally that will apply directly to
HTML elements. Generally, styling HTML elements globally should be avoided,
however, styling headings in this manner can help ensure authored content
(possibly provided via a CMS) renders with the relevant hierarchical
presentation.

Take the following CSS, for example, with font size values generated from
[modularscale.com](https://modularscale.com):

```css
h1,
h2,
h3,
h4,
h5,
h6 {
  font-weight: 700;
  font-family: serif;
}

h1 {
  font-size: 2.986rem;
}

h1 {
  font-size: 2.488rem;
}

h3 {
  font-size: 2.074rem;
}

h4 {
  font-size: 1.728rem;
}

h5 {
  font-size: 1.44rem;
}

h6 {
  font-size: 1.2rem;
}
```

### Providing Semantic Control

With styling handled, now we need a re-usable way to generate the heading level
from a single component:

```jsx
import React from 'react'
import './heading-styles.css'

function Heading({ as, children }) {
  const Component = as

  return <Component>{children}</Component>
}

function MyPage() {
  return (
    <>
      <Heading as="h1">My Page</Heading>

      <Heading as="h2">More Information</Heading>
    </>
  )
}
```

### Separate Form from function

With the DOM rendering handled, now we incorporate a new prop `looksLike` that
helps divorce presentation from the underlying semantics. In this example, we
leverage the
[ARIA heading role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role)
paired with the `aria-level` attribute in order to have more granular control
over the DOM semantically:

```jsx
import React from 'react'
import './heading-styles.css'

function Heading({ as, looksLike, children }) {
  const Component = looksLike ? looksLike : as
  const headingLevel = as.replace('h', '')

  return (
    <Component role="heading" aria-level={headingLevel}>
      {children}
    </Component>
  )
}

function MyPage() {
  return (
    <>
      <Heading as="h1">My Page</Heading>

      <Heading as="h2" looksLike="h3">
        More Information
      </Heading>
    </>
  )
}
```

Now, the "More Information" heading _looks_ like a level 3 heading, but is
semantically a level 2 heading.

## Conclusion

Building a re-usable, accessible component abstraction can help improve the
developer experience of a project while also improving the end-user experience.
Spending a little time to introduce such an abstraction can pay off in the long
run, allowing for easier feature development, all while lowering the risk of
accessibility defects.


Learn how to build a re-usable, accessible heading component with React.

Building an Accessible, Re-usable Heading Component

---
title: Encouraging Accessibility Best Practices with Cypress.io
description:
  How to write automated tests that encourage others to adopt best practices and
  avoid introducing invalid HTML.
date: '2021-01-24'
image: 'maarten-deckers-T5nXYXCf50I-unsplash.webp'
---

When building a web site or application with accessibility in mind, laundry
lists of rules and requirements come to mind. This often leads organizations to
adopt [accessibility checklists](http://accessibility.voxmedia.com/) that
hopefully provide designers and engineers with a concrete series of requirements
that all products must meet.

Despite their complexity, nearly all of these requirements start with a
foundation in semantically valid HTML. Though this may sound like a low bar to
meet, many engineers struggle to write semantically valid markup, particluarly
when those engineers may have more expertise in pure programming rather than the
ins-and-outs of HTML.

## Abstractions Upon Abstractions

When building for the web using modern JavaScript frameworks, oftentimes the
actual DOM that is being rendered to the page is abstracted away via several
layers of custom components. These abstractions are great on the surface - they
allow for code re-use, visual consistency, and UX consistency. Unfortunately,
custom components can also cause engineers to lose the forest for the trees, and
ignore the final, rendered markup with which end users interact.

Take this JSX that renders a page with a data table of recipes:

```jsx
export function MyRecipesPage() {
  <Page title="My Recipes">
    <SortableTable data={recipes}>
    <Button to="/">Go Back</Button>
  </Page>
}
```

Looks great! The page works as expected and the code is easy to read thanks to
component abstractions. But how can an engineer have confidence that these
components are rendering valid markup? What if that `<Button>` component is
incorrectly rendering an HTML button instead of an anchor tag? What if
`<SortableTable />` is just a series of `div` and `span` tags rather than a
semantically meaningful data table?

## Automated Testing

Ideally, a layer of automated testing at the component level would catch these
problems, while also encouraging engineers to choose components available to
them that render semantically valid markup.

### Enzyme Shallow Mounting

For years in the React community, testing a page component like this would
probably start with using [Enzyme](https://enzymejs.github.io/enzyme/), a
library with utilities for testing React components in a Node-based virtual DOM
environment like [jsdom](https://github.com/jsdom/jsdom#readme). One would
probably start with something like this using Enzyme's `shallow` method:

```js
describe('MyRecipesPage', () => {
  it('renders a Page with a title', () => {
    const wrapper = shallow(<MyRecipesPage />)
    const page = wrapper.find('Page')

    expect(page).toExist()
    expect(page).toHaveProp('title', 'My Recipes')
  })

  it('renders a SortableTable with recipes data', () => {
    const mockRecipes = []
    const wrapper = shallow(<MyRecipesPage recipes={mockRecipes} />)
    const table = wrapper.find('SortableTable')

    expect(table).toExist()
    expect(table).toHaveProp('data', mockRecipes)
  })

  it('renders a Button that returns the user to the landing page', () => {
    const wrapper = shallow(<MyRecipesPage recipes={mockRecipes} />)
    const button = wrapper.find('Button')

    expect(button).toExist()
    expect(button).toHaveProp('to', '/')
  })
})
```

These tests look like they are verifying the rendered output - but all they are
doing is verifying that the components used in the page component were actually
returned. Do these tests provide future engineers with confidence in the final
rendered DOM? Assuming future engineers were interested in testing the HTML
semantics of the page, they might be concerned with answering the following
questions:

- Does `<MyRecipesPage />` have a valid heading?
- Is the data rendered in a valid HTML table?
- Does the button actually render as a link or does it (incorrectly) render as
  an HTML button?

### Cypress to the Rescue

Refactoring these tests with [Cypress](https://cypress.io) can help address some
of these concerns:

```js
describe('"My Recipes" page', () => {
  beforeEach(() => cy.visit('/recipes'))

  it('renders with a relevant page title', () => {
    cy.title().should('include', 'My Recipes Page') // Checking for a unique <title />
    cy.get('h1').should('be.visible').should('contain', 'My Recipes Page')
  })

  it('renders with a table that contains recipe data', () => {
    cy.get('table').should('be.visible')
    // Verify data renders as expected
    cy.get('tbody tr').eq(0).should('contain', 'Chicken Pot Pie')
    cy.get('tbody tr').eq(1).should('contain', 'Green Curry')
  })

  it('renders with a link to go back to the home page', () => {
    cy.get('a')
      .should('be.visible')
      .should('contain', 'Go Back')
      .should('have.attr', 'href', '/')
  })
})
```

Great! Now these tests run in the browser _and_ are grabbing elements from the
DOM instead of React component abstractions that may or may not be producing the
markup we are expecting.

These tests can be taken a step further using
[Cypress Testing Library](https://www.npmjs.com/package/@testing-library/cypress).

#### Cypress Testing Library

Cypress Testing Library offers a series of methods to help query elements more
granularly, allowing room for code refactors as well as the addition of new
features to the page. If the page were to introduce an additional link, for
example, the prior test checking for the home page anchor tag would fail:

```jsx
export function MyRecipesPage() {
  <Page title="My Recipes">
    <SortableTable data={recipes}>
    <Button to="/">Go Back</Button>
    <Button to="https://google.com">Find More Recipes</Button>
  </Page>
}
```

And now this test would need to changed:

```js
it('renders with a link to go back to the home page', () => {
  // This test was broken by the introduction of another anchor tag!
  // Not ideal since the original "Go Back" link continued to work as expected.
  cy.get('a')
    .eq(0)
    .should('be.visible')
    .should('contain', 'Go Back')
    .should('have.attr', 'href', '/')

  cy.get('a')
    .eq(1)
    .should('be.visible')
    .should('contain', 'Find More Recipes')
    .should('have.attr', 'href', 'https://google.com')
})
```

Instead of grabbing raw HTML elements, the `cy.findByRole` method (made
available via Cypress Testing Library) can be used to check for valid,
accessible DOM output all while reducing the risk of test brittleness:

```js
describe('"My Recipes" page', () => {
  beforeEach(() => cy.visit('/recipes'))

  it('renders with a relevant page title', () => {
    cy.title().should('include', 'My Recipes Page')
    // Using the `name` option helps grab the relevant heading that contains the content we are looking for
    cy.findByRole('heading', { name: 'My Recipes Page' }).should('be.visible')
  })

  it('renders with a table that contains recipe data', () => {
    cy.findByRole('table').within(() => {
      cy.get('tbody').within(() => {
        cy.findAllByRole('row').eq(0).should('contain', 'Chicken Pot Pie')
        cy.findAllByRole('row').eq(1).should('contain', 'Green Curry')
      })
    })
  })

  it('renders with a link to go back to the home page', () => {
    // This test will not be as brittle - it will find a link that has this content
    // no matter how many links are added to the page.
    cy.findByRole('link', { name: 'Go Back' }).should('have.attr', 'href', '/')
    cy.findByRole('link', { name: 'Find More Recipes' }).should(
      'have.attr',
      'href',
      'https://google.com'
    )
  })
})
```

So Cypress Testing Library helped solve three key problems with testing the
recipes page UI:

1. The tests are much less brittle now that they no longer rely on the order of
   DOM elements (nor will they break when new elements are introduced to the
   page)
2. The tests are able to handle valid HTML semantics whether they are derived
   from native HTML tags _or_ valid
   [ARIA roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques)
3. When future engineers work on this page, it will be more difficult to
   introduce invalid HTML even if such a bug were introduced via a higher level
   abstraction

An engineering team that leans heavily on `cy.findByRole` as their primary means
of querying elements in their tests will also catch accessibility problems
earlier. If an element is tough to query via `cy.findByRole`, that probably
means that a screen reader user (or even search engine crawler) would have
trouble interpreting the page as well and is an early indication that an
accessibility bug is present.

### Wrapping Up

Moving away from testing higher level abstractions with tools like
[Enzyme](https://enzymejs.github.io/enzyme/) helps protect against the
introduction of invalid markup. By leveraging [Cypress](https://cypress.io) and
[Cypress Testing Library](https://github.com/testing-library/cypress-testing-library)
(particluarly the `cy.findByRole` method) engineers can make automated testing
less brittle _and_ ensure their markup is meeting accessibility requirements all
within a real browser environment.


How to write automated tests that encourage others to adopt best practices and avoid introducing invalid HTML.

Encouraging Accessibility Best Practices with Cypress.io

---
title: Accessible Buttons that Look Like Links
description:
  Many links on the web look like buttons - but should they be coded as anchor
  tags or buttons?
date: '2020-08-25'
image: 'kenan-alboshi-UCbY7s2bF4o-unsplash.webp'
---

Semantically, the anchor tag should only be used when clicking on said element
navigates the user to a new page. Frequently, developers utilize the `<a>` for
clickable elements, even elements that open modals or trigger other state
changes within the current page.

When the wrong element is used, screen reader and keyboard-only users have a
tremendous amount of trouble interacting with the page. With React, for example,
it's very easy to add an `onClick` handler to an anchor tag that controls page
state rather than the current page. Take the following example:

```jsx
import React, { useState } from 'react'
import { Modal } from '../components'

function MyPage() {
  const [isModalOpen, setModalOpen] = useState(false)

  return (
    <div>
      <h1>I am the best page in the universe</h1>

      <a onClick={() => setModalOpen(true)}>Learn More About The Best Page</a>

      {isModalOpen && (
        <Modal>
          <p>
            Seriously, this is the best page in the universe. If only a
            keyboard-only user could use it.
          </p>

          <a onClick={() => setModalOpen(false)}>Close</a>
        </Modal>
      )}
    </div>
  )
}
```

Though clicking on "Learn More About The Best Page" will open the modal, there
are multiple problems with this implementation:

1. The anchor tag has the incorrect `role` to describe its behavior - it should
   either be a `<button>` element or have `role="button"`
2. Any anchor tag without an `href` attribute is not keyboard focusable

## Solutions

### Just Use a Button

Many accessibility advocates, having encountered many inaccessible
implementations of button-like links that are not actually links, advocate for a
blanket ban on the use of the anchor tag when they do not navigate to a new
page. Their argument is generally correct. Where possible, simply use a
`<button/>` instead of an anchor tag for interactive elements that do not
navigate the user to a new page.

That being said, there are instances in which a button that looks like a link
can be beneficial to the end user. Say, for example, within a paragraph of text
a user encounters a link that triggers an action on the page. Depending on your
product's CSS architecture, introducing a `<button/>` could wreak havoc from a
styling perspective.

### Use a Custom Component

In these scenarios, creating a re-usable component is the best way to prevent
the introduction of inaccessible links in to your product.

In order for a button to be interpreted correctly by screen readers _and_ be
usable for keyboard-only users, our `ButtonLink` component must have two key
features:

1. It must be a button semantically by adding `role="button"` and
2. It must be keyboard accessible by having a valid `href` attribute

```jsx
import React from 'react'

function ButtonLink({ children, onClick }) {
  const handleClick = (e) => {
    e.preventDefault()
    onClick()
  }

  return (
    <a href="#" role="button" onClick={handleClick}>
      {children}
    </a>
  )
}
```

Critically, this component provides a valid `href` making it keyboard
accessible. Unfortunately, any anchor elements with `#` do come with some
default behavior in the browser. In this example, we avoid the problem by
passing in the click event and invoking `e.preventDefault()` before invoking the
passed in `onClick` handler.

### Prevent Future Mistakes

This solution works well, however, there is still some risk that new developers
working on your product might introduce inaccessible button-like links in the
future. In order to help reduce that risk, introduce a simple console warning in
the event an `onClick` handler is passed to an anchor tag inappropriately. Say,
for example, our product has a generic, re-usable, `PageLink` component:

```jsx
import React from 'react'
import { Link } from 'react-router-dom'

function PageLink(props) {
  const { to, children } = props

  if (props.onClick) {
    console.warn(
      'Invalid prop `onClick` - avoid attaching click handlers to links. Use the `ButtonLink` component instead.'
    )
  }

  return <Link to={to}>{children}</Link>
}
```

## Wrapping Up

It's important to ensure that _all_ elements within a product can be both
interpreted by screen readers _and_ remain interactive for keyboard-only users.
Fortunately, by creating a custom, re-usable component and by providing
informative warnings, we can greatly reduce the risk of introducing common
accessibility bugs.


Many links on the web look like buttons - but should they be coded as anchor tags or buttons?

Accessible Buttons that Look Like Links

---
title: Automated UI Testing to Build Confidence
description:
  Automated tests should help teams ship confidently and quickly by building
  confidence.
date: '2019-09-19'
image: 'arturo-castaneyra-xLyOGT8i1qA-unsplash.webp'
---

The frontend ecosystem is rife with frameworks, tools, and libraries to help
make automated testing of user interface a cornerstone of ongoing development.
Like much of the JavaScript world, there are so many tools available, it can be
daunting to make a decision and move forward with an approach. This can be
particularly challenging when team members have different perspectives on what
problem is being solved with in the first place.

## The Problem

At the end of the day, tests are designed to address one thing - confidence that
your code is doing what it was meant to do. This confidence is important to
maintain from two distinct perspectives:

1. The developer perspective
2. the user perspective

### The Developer Perspective

A developer needs to know that a given library or module functions as expected
with confidence. When someone reaches for React or Lodash, they can safely
assume that these libraries work as advertised, as they are backed up by unit
tests to ensure that inputs always result in their intended outputs.

To give a common example, let's say we have a function called `add` that returns
the sum total of the two passed in values:

```javascript
function add(valueOne, valueTwo) {
  return valueOne + valueTwo
}
```

As a developer, I need to be confident that `add(3, 5)` returns `8` with
confidence! If I use this function within a user interface, however, the user
does _not_ need to know that `add(3, 5)` returns `8`. This is the key difference
between the developer perspective and the user perspective.

Tests that support the developer perspective generally take the form of unit
tests. Within the JavaScript world, using [Jest](https://jestjs.io) is the
defacto standard. By using Jest (and authoring code
[functionally](https://en.wikipedia.org/wiki/Functional_programming)), one can
ensure that an API (whether its a component API like a React component or
otherwise) remains consistent and predictable over time.

### The User Perspective

A user, on the other hand, has no idea _how_ an interface works nor should they
care. All the user is concerned with is accomplishing their goal through the UI.
In fact, authoring tests that test UI implementation details are probably a time
sink that not only wastes time upfront but also hampers future efforts by making
refactoring more difficult.

To most closely emulate the user's experience, tests that support the user
perspective should check the DOM directly rather than implementation details
like React components and their props. This can be accomplished in a few ways:

1. Authoring integration tests using a library like
   [Airbnb's Enzyme](https://github.com/airbnb/enzyme) or
   [React Testing Library](https://github.com/testing-library/react-testing-library)
   and avoiding
   [shallow rendering](https://airbnb.io/enzyme/docs/api/shallow.html)
2. _and_ using a tool like [Selenium](https://www.seleniumhq.org/) or
   [Cypress](https://cypress.io) for additional integration testing as well as
   end-to-end testing

### A Cohesive Strategy

In order to best address the concerns of both developers and users, using a
combination of **unit testing**, **integration testing**, and **end-to-end
testing** is the recommended approach.

#### 1. Unit Tests for Developers

For re-usable UI components, write unit tests to ensure that components produce
results based on passed in props using
[shallow rendering](https://airbnb.io/enzyme/docs/api/shallow.html):

```javascript
import React from 'react'
import { shallow } from 'enzyme'
import Collapsible from './Collapsible'

describe('Collapsible', () => {
  it('renders the open state when passing `true` to the `isOpen` prop', () => {
    const wrapper = shallow(<Collapsible isOpen={true} />)

    expect(wrapper.find('button')).toHaveProp('aria-expanded', 'true')
    expect(wrapper.find('CollapsibleContent')).toExist()
  })
})
```

This test provides developers with a reasonable level of confidence that passing
in `true` to the `isOpen` prop produces the desired result. In this case, the
developer knows that the relevant WAI-ARIA attribute will be updated _and_ the
content of the collapsible component will be visible. Its important to note that
this test will fail if the component implementation is refactored. For example,
if the prop name changes from `isOpen` to `open`, the test will fail even if the
user interaction continues to work as expected - such a change would represent a
change in the exposed component API - and as a result, would be a breaking
change for developers using the component rather than for users.

#### 2. Unit Tests for Users

For UI components, write unit tests that simulate user interaction using
[mount](https://airbnb.io/enzyme/docs/api/ReactWrapper/mount.html) to
realistically emulate the actual environment in which the interaction will take
place. In this scenario, a custom `.toHaveTextContent` matcher is being used
with Enzyme in order to avoid testing implementation details like class names,
IDs, or even HTML elements:

```javascript
const toHaveTextContent = (received, expectedContent) => {
  const text = received.debug && received.debug()

  return {
    message: () => `expected component to have content "${expectedContent}"`,
    pass: RegExp(expectedContent).test(text),
  }
}

export default toHaveTextContent
```

```javascript
import React from 'react'
import { mount } from 'enzyme'
import Collapsible from './Collapsible'

describe('Collapsible', () => {
  it('opens when clicked', () => {
    const wrapper = mount(
      <Collapsible>I am content that will show and hide</Collapsible>
    )

    wrapper.find('button').simulate('click')

    expect(wrapper.find('button')).toHaveProp('aria-expanded', 'true')
    expect(wrapper).toHaveTextContent('I am content that will show and hide')
  })
})
```

This test provides developers with confidence that the user can interact with
the component in a consistent manner that will continue to remain relevant even
if the underlying component implementation is refactored.

#### 3. Integration Tests

For flows and features, write integration tests using
[Cypress](https://cypress.io) to ensure that components work well together when
handling real user interactions and mock API requests that match any contracts
between the frontend and the backend with regards to data structure.

Testing the UI using fixtures is relatively straightforward. First, we author a
fixture as a JSON file called `accounts.json`:

```json
[
  {
    "type": "savings",
    "name": "My Savings Account"
  },
  {
    "type": "checking",
    "name": "My Checking Account"
  }
]
```

We then reference `accounts.json` as a fixture, using that data to render the
view instead of a real network request:

```javascript
/// <reference types="Cypress" />

describe('The accounts collapsible', () => {
  before(() => {
    cy.server()
    cy.visit('/accounts')
    cy.route('GET', 'accounts/*', 'fixture:accounts.json')
  })

  it('renders the accounts list when clicked on', () => {
    cy.contains('My Accounts').click()

    cy.contains('My Savings Account').should('be.visible')
    cy.contains('My Checking Account').should('be.visible')
  })
})
```

**NOTE:** This sort of testing is not possible with Selenium-based testing tools
as Selenium does not have access to the browser directly! From my perspective,
this is the primary reason to use Cypress over other available end-to-end
testing tools.

#### 4. End to End Tests

For very important flows and features, write end-to-end tests using either
Cypress or Selenium. For simplicity's sake, this example will use Cypress to
clearly demonstrate the distinction between the integration and end-to-end test:

```javascript
/// <reference types="Cypress" />

describe('The accounts collapsible', () => {
  before(() => {
    cy.visit('/accounts')
  })

  it('renders the accounts list when clicked on without errors', () => {
    cy.contains('My Accounts').click()

    cy.contains('Accounts failed to load').should('not.be.visible')
  })
})
```

In this situation, because the relevant account names and content are not known
ahead of time, making assertions based on those results is not possible,
however, we do want to check that the request succeeds and that no error occurs.
Cypress also automatically fails tests that cause errors in the console, and as
a result, just visiting and interacting with the page increases confidence in
the implementation.

## Final Thoughts

Ultimately, automated tests should promote confidence in the product that is
being developed such that developers can easily make changes to a codebase all
while understanding the impacts those changes have. In order to develop this
level of confidence within a project, the right testing approach has to be used,
otherwise tests can become a source of frustration rather than a means by which
to work more efficiently and improve the end user experience.


Automated tests should help teams ship confidently and quickly by building confidence.

Automated UI Testing to Build Confidence

---
title: A Typescript Monster Battler
description:
  Read about my very early explorations with TypeScript by building a tiny game
date: '2019-02-12'
image: 'anders-jilden-Sc5RKXLBjGg-unsplash.webp'
---

I was inspired to finally bite the bullet and try out Typescript after listening
to NPM's Laurie Voss on
[Shop Talk Show Episode 345](https://shoptalkshow.com/episodes/345/). The
following is a brief run through of what I discovered along the way.

## A Project

I've always been curious about game development, and as such, wanted to use this
opportunity to dip my toe in to some basic text-based gaming mechanics through a
Node.js application. I knew I could pretty quickly build some JavaScript modules
for rolling dice, determining NPC stats, and ultimately, simple turn-based
combat. Why not spice things up with Typescript while I'm at it?

### Tools

I had some basic architectural requirements I wanted to stick with when
authoring my first TypeScript app:

1. Use Node.js to build a text-only interface,
2. Make use of ES6 modules,
3. and use [Jest](https://jestjs.io) for unit testing

This structure was mainly meant to mimic common tools I typically use during
day-to-day work.

## Getting Started

### The Build

#### ES6 Modules in Node.js

I've gotten used to writing JavaScript modules using the newer,
[ES6 import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import)
syntax. Node.js (at least at the time of writing!) does not play nicely with
said syntax by default, but that's easy to resolve with a build in flag and the
`.mjs` file extension:

```bash
node --experimental-modules ./index.mjs
```

#### TypeScript

After initializing a project through NPM, installing TypeScript is easy enough:

```bash
npm install typescript --save-dev
```

I then leveraged NPM's somewhat new `npx` feature to run the TypeScript CLI and
compile `.ts` files to JavaScript.

##### Handling .mjs

But wait a minute, don't these files need to be compiled to `.mjs` rather than
`.js` if I want to use ES6 imports? A small file named `toMJS.bash` to the
rescue:

```bash
#!/bin/bash

for file in ./dist/*.js
do
  mv "$file" "${file%.js}.mjs"
done
```

#### Bringing the Build Together

Using NPM scripts, all of the commands can be brought together quite nicely via
the `package.json`:

```json
"scripts": {
  "clean": "rm -rf ./dist",
  "build": "npm run clean && npx tsc",
  "prepare": "sh toMJS.bash",
  "start": "npm run build && npm run prepare && node --experimental-modules ./dist/index.mjs"
}
```

### Testing

Writing tests using Jest is a breeze - it's easy to get started, simple to
configure, and runs tests efficiently. Making it work with TypeScript, however,
did require a bit of know-how.

#### Playing Nicely with TypeScript

Installing Jest is very straightforward:

```bash
npm install jest --save-dev
```

Unfortunately, at least at the time of writing, Jest does not support TypeScript
out of the box. That's nothing a good `npm install` can't solve!

```bash
npm install ts-jest @types/jest --save-dev
```

A little configuration in the `jest.config.js` and we are up and running:

```json
"transform": {
  "^.+\\.tsx?$": "ts-jest"
},
"testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
```

#### Playing Nicely with ES6 Imports

Like Node, Jest does not support ES6 modules out of the box. Once again, our
friend `npm install` will save us.

```bash
npm i @babel/core @babel/preset-env babel-jest --save-dev
```

And just some tiny configuration in a `.babelrc` file:

```json
{
  "presets": ["@babel/preset-env"]
}
```

## Writing Some Modules

I won't go in to detail regarding all of the modules in the project, as those
can easily be found in the
[GitHub Repo](https://github.com/nicklemmon/typescript-monster-battler),
however, I hope to go over how I leveraged TypeScript features when authoring.

### Rolling a Die

Rolling "dice" is pretty straightforward. A simple JavaScript function can
handle the work, and with TypeScript, required parameters have types. Here is
`rollDie.ts`:

```typescript
export default function rollDie(numberOfSides: number = 6) {
  return Math.floor(Math.random() * numberOfSides) + 1
}
```

Types paired with
[default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters)
really offer some power! Not only will future developers be restricted to
passing in numbers when it comes to the number of sides on a virtual die, but
they won't have to pass in anything if they want to use a traditional 6-sided
die.

### A Monstrous Interface

[Interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html) allow
consistent, predictable structuring of objects, and in this project's case,
monsters!

```typescript
export default interface Monster {
  name: string
  strength: number
  dexterity: number
  toughness: number
  vitality: number
}
```

And later, in our `index.ts`, we create a `Cyclops` that leverages the `Monster`
interface:

```typescript
const Cyclops: Monster = {
  name: 'Cyclops',
  strength: 10,
  dexterity: 2,
  toughness: 8,
  vitality: 10,
}
```

We can even use this interface to build other functions, particularly functions
that accept a `Monster` as an argument. For example, the `getHP()` function:

```typescript
import Monster from './Monster'

export default function getHitPoints(monster: Monster) {
  return monster.toughness + monster.vitality * 2
}
```

## Final Thoughts

Authoring with TypeScript has some clear benefits. Predictability and
consistency are enforced via a system of checks that occur when TypeScript is
compiled, reducing the risk of defects and making code more concise.

Though the benefits are clear, ideally, both Node and Jest would support
TypeScript out of the box. Getting a working development environment is feasible
with current tools, however, takes a little more work than I expected
considering the popularity of the language. Hopefully as the web development
community continues to welcome our new TypeScript overlords, the tooling can
catch up appropriately.

### Helpful Links

- The full
  [TypeScript Monster Battler](https://github.com/nicklemmon/typescript-monster-battler)
  repo
- [ts-jest NPM package](https://www.npmjs.com/package/ts-jest) to leverage
  TypeScript with Jest


Read about my very early explorations with TypeScript by building a tiny game

A Typescript Monster Battler

---
title: Building an Accessible Collapsible Element
description:
  Learn how to build an accessible expandable/collapsible custom component that
  meets WAI-ARIA standards.
date: '2018-11-10'
image: 'grant-ritchie-_-gToenDbXg-unsplash.webp'
---

When it comes to JavaScript-based interactions, an accessible user experience is
not a given. Even simple interactions require a certain structure.

## Enter ARIA

For those new to developing with accessibility in mind, `aria-` attributes are
used to add additional descriptive information regarding the current state of a
component, particularly components that change dynamically based on user
interaction.

### Using the aria-expanded Attribute

`aria-expanded` informs screen readers that an element is expandable and/or
collapsible. Though this is often conveyed visually, if `aria-expanded` does not
describe the change on the page, then the change is not communicated at all to
users who cannot see said change.

Here is a simple HTML example of an accordion in the collapsed state:

```html
<div class="accordion">
  <button aria-expanded="false" class="accordion__button">
    Example Accordion Button
  </button>

  <div class="accordion__content" style="display: none;">
    <p>Here is some initially hidden content.</p>
  </div>
</div>
```

And another example, this time in the expanded state:

```html
<div class="accordion">
  <button aria-expanded="true" class="accordion__button">
    Example Accordion Button
  </button>

  <div class="accordion__content" style="display: block;">
    <p>Here is some initially hidden content.</p>
  </div>
</div>
```

### Using the aria-controls Attribute

`aria-controls` can be used in conjunction with `aria-expanded` to properly
associate the content of the expanding and collapsing element with the
triggering button element. `aria-controls` must have a value that matches the
`id` of the controlled element. _Remember_ it is _critical_ that _every_ ID on a
page is unique!

```html
<div class="accordion">
  <button
    aria-expanded="false"
    class="accordion__button"
    aria-controls="example-id"
  >
    Example Accordion Button
  </button>

  <div class="accordion__content" style="display: none;" id="example-id">
    <p>Here is some initially hidden content.</p>
  </div>
</div>
```

### Working Examples

- The WAI-ARIA authoring group has provided
  [this example](https://www.w3.org/TR/wai-aria-practices/examples/disclosure/disclosure-img-long-description.html)
- and I built an example [on CodePen](https://codepen.io/nicklemmon/pen/wJXadm)
  awhile back using [Pug.js](https://pugjs.org/).

## Conclusion

When building stateful components, its important to ensure that these states are
adequately perceivable for all users. In fact, in order to meet the standards
set out by the Web Content Accessibility Guidelines (WCAG), all page behavior
and content _must_ first be
[perceivable](https://www.w3.org/TR/WCAG21/#perceivable) to all users.


Learn how to build an accessible expandable/collapsible custom component that meets WAI-ARIA standards.

Building an Accessible Collapsible Element

---
title: Using tabindex Effectively
description:
  Changing the value of the tabindex can be dangerous - but sometimes critically
  important. Learn how to use this attribute safely.
date: '2018-11-03'
image: 'pierre-chatel-innocenti-YDarsL40neU-unsplash.webp'
---

From where I stand, `tabindex` is an underutilized HTML attribute. That being
said, when used incorrectly, it can prove disastrous! Let's talk about the when
and the how of `tabindex`.

## Making "Non-Clickable" Elements Focusable

With JavaScript, its easy to make an element clickable. Either through DOM
manipulation or via a framework like React, making a `<div>` as interactive as a
`<button>` is trivially easy. Unfortunately, a `<div>` will not be a part of the
document's tab order like a `button`! That's where `tabindex` comes in handy.

Let's say we have a `<div>` that opens up a modal when clicked like so:

```html
<div class="button">I trigger some behavior.</div>
```

By default, the keyboard cannot find this element, and thus, neither will screen
readers be informed that the elememnt is interactive. This is a huge problem
from an accessibility standpoint! This is a clear violation of the
[WCAG 2.1 guideline](https://www.w3.org/TR/WCAG21/#keyboard-accessible)
regarding keyboard accessibility.

To remedy that, add `tabindex="0"` _and_ `role="button"` to inform screen
readers that the element is interactive.

```html
<div class="button" tabindex="0" role="button">I trigger some behavior.</div>
```

Ta-dah! The element can now receive keyboard focus whenever the user hits the
tab key.

## Making Elements Programmatically Focusable

With JavaScript, moving focus to an element is often required in order to help
improve user experience, and frequently a must-have when making complex
interactions accessible for all users. THat being said, focus can't be moved to
just any old element. Consider the following example:

```html
<div class="alert alert--error" id="my-alert">Warning! Invalid password.</div>
```

Let's say we want to move focus to this alert:

```javascript
document.querySelector('#my-alert').focus()
```

Unfortunately this won't work! We need to first add _some_ value for `tabindex`.
So let's try `tabindex="0"` like before:

```html
<div class="alert alert--error" id="my-alert" tabindex="0">
  Warning! Invalid password.
</div>
```

Woohoo! This works. Sort of.

Unfortunately, what we've done is introduced the alert in to the keyboard tab
order. As a user tabs through interactive elements, they then encounter the
alert, only to find that it isn't actually an interactive element.

### Negative tabindex to the Rescue!

This is when leveraging `tabindex="-1"` comes in to play. This makes the element
both programmatically focusable _and_ keeps the element outside of the tab order
of the document.

So, we end up with:

```html
<div class="alert alert--error" id="my-alert" tabindex="-1">
  Warning! Invalid password.
</div>
```

### Other Values for tabindex

Other, positive values are technically valid for use with `tabindex`, however,
these should _pretty much never ever be used_. By supplying positive values for
`tabindex`, the "natural" tab order of the page can be modified, unfortunately
resulting in accidental keyboard tab traps, a big
[accessibility no-no](https://www.w3.org/TR/WCAG21/#no-keyboard-trap).

## Wrapping Up

`tabindex` is a critically important attribute, particularly when working to
build a page that is usable for keyboard-only users _and_ our friendly
neighborhood power user.

To summarize:

1. Add `tabindex="0"` to elements that are typically non-interactive that have
   been made interactive by JavaScript
2. Add `tabindex="-1"` to elements that need to receive focus programmatically
   but should not be a part of the keyboard order of the document and
3. Never _ever_ use a positive value for `tabindex`


Changing the value of the tabindex can be dangerous - but sometimes critically important. Learn how to use this attribute safely.

Archives