Forem: Alec Lomas

Styling Links for Print

Alec Lomas — Fri, 03 Jul 2020 00:00:00 +0000

A few weeks ago, amid the ongoing COVID-19 pandemic, my apartment building left a note in my mailbox. Among the helpful information and polite requests to wear masks in shared areas, I noticed a piece of text that had a very familiar style. It was blue, and underlined, and seemed to hint at a missing piece of content. In short, it was a link. Of course, this being a printed piece of mail, the link wasn't much help to me. And, while this note was certainly a Google Docs or Word document, it made me think about the way links are styled on the web.

While people aren't printing out websites at the same volume they used to, print styles are still very important. Modern browsers use these styles when saving a page as a PDF, for example. The problem is that links in this context are not always clickable. But with a little CSS we can ensure the user is always shown the URL the link points to:

@media print {
  a:link[href^='http']::after {
    content: ' (' attr(href) ')';
  }

  a:link[href^='/']::after {
    content: ' (https://mywebsite.com' attr(href) ')';
  }

  a:link[href^='#'] {
    text-decoration: none;
  }
}

This CSS takes advantage of the print media query to set special styles on links in that context. Specifically, we are creating a psuedo-element on links that begin with http (absolute links) and / (root-relative links). The content of those elements is set to the link element's href attribute using the attr function. As a bonus, we also remove the link-styling for anchor links, since those have no practical purpose in print contexts.

Of course this isn't an advised solution to every link, but it is particularly useful for blog posts, technical documentation, and any content that a user might want to save to refer to later. Printing websites not be a common occurrence anymore, but setting print styles absolutely should be.

No Red Squigglies For Semicolons

Alec Lomas — Wed, 04 Dec 2019 00:00:00 +0000

Us developers are an opinionated bunch. We share our opinions wide and loud through blog posts, tweets, talks at meetups, in meetings. The tenacity with which we hold these opinions seems to have an inverse correlation with their impact, and nowhere is this strange dichotomy more present than in stylistic choices. Should we use tabs or spaces for whitespace? Should we use semicolons or not? Single quotes or double quotes?

Collectively, these stylistic choices are known as bikeshedding. Thousands of words have been written about how we should be painting our bikesheds. We have many tools to help us paint the bikeshed. But, truth be told, I don’t care much about what color the bikeshed is. What I do care about is my code editor’s linting extension putting a red squiggly line under a function declaration because there’s a space between the name of the function and its parameter list.

Linters Are For Code Quality, Formatters Are For Style

Linters are incredible code quality tools. They enforce best patterns and can help catch bugs well before our code makes it to a browser. But they are ill-equipped to handle issues of style. Attempting to use an undefined variable is a bug, and your linter should point this out to you. Using single quotes instead of double quotes, on the other hand, will not impact your code’s logic or ability to run. As such, your linter should not care about this issue. At the very least it should not interrupt your work to tell you about it.

Formatters are a different kind of tool altogether. They care only about enforcing a consistent style and rarely (if ever) give real-time feedback. Instead, they wait until your work is at a safe stopping point to run: when you save a file, when you commit, or when you explicitly tell the formatter to run. Because of this, they are much less likely to introduce friction into your workflow.

In the JavaScript world the most used linter is ESLint, and the most used formatter is Prettier. They’re what I use across my projects. Unfortunately, many popular ESLint configs include strict enforcement of stylistic rules. Recognizing that conflicts between the two tools would arise, the Prettier team created eslint-config-prettier. The aptly-named ESLint config turns off any rules that conflict with Prettier, giving it full dominion over all issues of style. Using it allows us to keep the code quality benefits of our linter, only without those pesky bikeshedding errors.

If You Have to Remember To Do It, You’ll Forget To Do It

The workflow friction does not stop with squiggly lines, of course. If your setup relies on you to remember to run a linter or formatter (or test suite) against your code, you will forget to do so. Probably not every time, maybe even not most of the time, but definitely some of the time. This is especially true when working in a shared codebase: we can’t be sure all members of our team have the same linting & formatting extensions installed, that those extenstions are configured the same way, or be sure our teammates will remember to run those tools manually. Instead, I find it better to set these tools up to run with Git hooks.

Git hooks allow us to run arbitrary commands when performing a Git function; they allow us to run scripts before or after committing or pushing or pulling. While possible to set these hooks up manually, tools like husky make setting them up much easier. I also often use a tool called lint-staged to lint & format only those files staged for commit. This makes the process much faster, and ensures that no extraneous files are included in a commit.

Combined with removing bikeshedding rules from your linter, introducing a formatter and setting up Git hooks will remove a fair amount of friction from your code writing process. Setting these tools up — ESLint, Prettier, husky, & lint-staged — are among the first things I do in any new JavaScript project. I highly recommend giving it a shot.

On Declarative Styling

Alec Lomas — Fri, 19 Jul 2019 08:09:07 +0000

There is a problem at the heart of CSS. It's not the cascade, or specificity, or inconsistencies between rendering engines -- though these things can be annoying. No, it's much simpler than that: the problem is that we can write too much of it.

I am not talking about append-only stylesheets (though these too cause their issues). Even if we're extremely disciplined about refactoring our CSS, and we only add new rules when absolutely needed, something is still wrong. The problem is the flexibility of the language itself. There are nearly unlimited valid values that a padding declaration can take, and while extremely freeing this also introduces surface area for inconsistencies in our designs. And consistency is key to good design! It reduces the end user's cognitive load, it (generally) looks better, and it minimizes the workload for designers & developers to boot.

Artificially limiting the number of values that we can use in declarations is key to avoiding these inconsistencies. We want a declaration like padding to act a little more like float; we should only be able to set a value that we've defined in our governing system. There are many techniques and technologies that can help us accomplish this (or at least get us close). I call the overarching concept that these tools encompass "declarative styling".

Defining "Declarative"

This term -- declarative styling -- is derived from the computer science concept declarative programming. It means we want to tell the computer the rules for drawing our interface, and let it follow those rules for us. We no longer want to write padding: 1rem, we want to write something like padding: 3 and have the computer replace the 3 with the 3rd value in our spacing scale.

This accomplishes several things for us. It ensures consistency across our design by allowing us to use a reference rather than a specific value. It also reduces the cognitive load for stakeholders by providing a common language to communicate in. These factors (among others) can make designing and iterating faster, and all but eliminate the inherent friction in designer-developer handoff.

Design Tokens

Those familiar with the concept of design tokens may find a lot of conceptual overlap here. Design tokens are an essential part of declarative styling: they are how we define our custom subset of styling options. If a rule in our stylesheet declares a background-color, that swatch should be found in our tokens.

There are many techniques for storing and parsing design tokens. I'm partial to the JSON-based System UI theme specification, which organizes our tokens into a variety of scales. Several of the tools discussed below rely on this or a similar technique, but the concept remains the same: there should be a source of truth for these values, and it should not be the CSS rule itself.

Techniques

Much like there are a multitude of ways to store our tokens, there are many, many ways to apply them to our styles.

CSS Variables

The most commonly-used solution, and one you're likely familiar with, is to use variables whenever possible. Although Sass and LESS have had variables since their inception, CSS now has native variable support with the custom properties specification.

.box {
  padding: var(--spacing-3);
}

Unlike the variables of preprocessors like Sass and LESS, custom properties can take full advantage of the cascade. This means we can create fully themeable component styles natively.

.btn {
  /* First we define our variables in the base component style */
  --button-padding-y: var(--spacing-2);
  --button-padding-x: var(--spacing-3);
  /* Then we apply our variables to our declarations */
  padding: var(--button-padding-y) var(--button-padding-x);
}

/* By updating our variables, the styles will change automatically */
.btn--large {
  --button-padding-y: var(--spacing-3);
  --button-padding-x: var(--spacing-4);
}

To take full advantage of this system, we need to convert our tokens to custom properties in the :root selector. The easiest way to do this is to copy and paste the values by hand, though there are tools to automate the process.

Of course, no method is without a downside. In this case, the biggest flaw is the same as its biggest draw: the low barrier to entry. There are no guardrails to stop you from writing padding: 24px instead of using your variable. It takes a lot of discipline to not deviate from the system, and any time you're writing new CSS is an opportunity to create a discrepancy. But combined with a strict code review process, this can be a powerful way of enforcing consistency while creating a themeable system.

Atomic CSS

Atomic CSS (aka Functional CSS, aka Utility-first CSS) libraries like BassCSS, Tachyons, and Tailwind CSS are declarative by definition. Classes like p3 automatically follow our padding rule from above: we're telling the engine to apply equal padding to all sides (the p) using the third step from our spacing scale (the 3).

<div class="p3">Hi</div>

Customizing BassCSS and Tachyons can be tough, but it is possible. Tailwind, on the other hand, is fully customizable by default. The Tailwind configuration system is a plain JS object exported from a Node script. A major benefit to this approach is that we can read our tokens from a JSON or YAML file, and apply them to our custom config with a few lines of code.

I'm on the record as being a big, big fan of atomic CSS. But I'm not blind to the disadvantages. The learning curve can be quite steep; not only do we need to internalize the naming scheme, but we also need to rethink how we apply our CSS. Because we also need to apply a fair amount of classnames to our components, I also tend to recommend this approach only for very simple projects or for projects that have a powerful templating system. Applying atomic CSS classes to a React component or Pug mixin makes applying the classnames to our elements much more palatable.

Styled System

The advent of CSS-in-JS has presented us with a unique opportunity: by taking advantage of an expressive, fully-featured programming language, we can create abstractions on top of CSS that would otherwise be impossible. For example, by taking the lessons learned from atomic CSS and applying them to a JSX-based CSS-in-JS system, Brent Jackson has created several purpose-built declarative styling libraries.

The first of these libraries, the foundation upon which the others are built, is called Styled System. The library provides a consistent interface to refer to your design tokens when defining or consuming a component. The true genius of Styled System is how it handles responsive styles. By default, Styled System props accept a string, which the library parses and converts to a value represented by a design token. If the token is not found, the literal value is passed to the underlying CSS-in-JS library. However, by passing a prop an array, it will apply the 0-index value to the component by default, the 1-index value to the component at the first breakpoint, and so on and so forth.

import styled from 'styled-components'
import { space, color } from 'styled-system'

const Box = styled.div`
  ${space}
  ${color}
`

const MyStyledSystemComponent = props => (
  <Box p={[2, 3]} color="primary" {...props}>
    Hi
  </Box>
)

This approach allows us to not only create components that are not only consistent with our system, but are extremely portable as well. A rule of thumb I try to follow when styling a component is to only define surrounding vertical margin when the component is actually consumed in a view. By spreading our props to a root component defined with Styled System, it becomes trivial to follow this rule.

const MyView = () => (
  <main>
    <header>...</header>

    <MyStyledSystemComponent my="4" />

    <footer>...</footer>
  </main>
)

Because Styled System (when used in React) reads from the theme put into context from your CSS-in-JS library of choice's ThemeProvider, creating themeable components is a breeze. However, attaching space, color, and other token references to all your components can be quite annoying. Luckily, Mr. Jackson has also created a library of primitive components built on top of Styled System called Rebass. These components operate like the Box component we utilized inside of MyStyledSystemComponent.

Most recently, Brent has released Theme UI, a further iteration of this idea. Theme UI exposes an sx prop on JSX components that allows us to reference our tokens, provides primitive components to use as a foundation, handles styling of markdown content with MDX, and much, much more. It's an exciting evolution of the approach, and one I intend to explore more fully in the future.

The Styled System approach, much like the others, comes with its fair share of downsides. For starters, it shares the same learning curve problem as atomic CSS. It can be somewhat cumbersome to set up, particularly when not using Rebass or Theme UI's primitive components. And while it can technically work with any framework that supports JSX, React is the only true first-class Styled System citizen. But, when given a choice, it is still my preferred method for defining and consuming styles.

A Vision of the Future

The web has always been an extremely flexible and expressive platform. This has lead to some amazing creative applications of technology, new media experiences, and beautiful interactions. It has also created plenty of footgun opportunities. By placing self-imposed constraints on the very fabric of the web, we get to remove the more self-sabotaging aspects of designing for the platform. Rather than limiting our creativity, these constraints provide guardrails for us to explore the limits of our designs while providing a consistent and visually harmonious interface to our users.

The declarative styling methodology will continue to evolve over time. As design tokens become more prevalent, design software will add first-class support for them. More libraries and methods will evolve for applying them to our products, both on the web and beyond. As we solve the problem at the heart of CSS, the language we use to communicate between ideation and implementation will meld into one. Perhaps our tools will as well.

This post originally appeared on my personal blog

Request Timeouts With the Fetch API

Alec Lomas — Sat, 30 Mar 2019 00:00:00 +0000

I’m a big fan of the Fetch API. I use it regularly in all sorts of projects, including my site and the API that powers the stats on the about page. However it isn’t always as clear how to do things like error handling and request timeouts as it is in libraries like Axios.

If you’re not familiar with fetch, it’s a native API that massively simplifies making AJAX requests compared to the older XHR method, and it’s supported in all modern browsers. When it initially landed, however, there was no easy way to handle request timeouts. You could fake it with Promise.race or by wrapping your fetch in another Promise, but these solutions don’t actually cancel the request. This is where AbortController comes in.

AbortController is an API that, much like its name and my previous sentence suggests, allows us to abort (cancel) requests. Though browser support isn’t wonderful at time of writing, it can be used in most modern browsers and polyfills are available. The API itself has a very small surface area: a signal property to attach to request objects, and an abort method to actually cancel the request. Because the API is so simple, it’s very flexible — Jake Archibald has a fairly in-depth article on the Google Developers blog going over various cancellation scenarios, as well as the history behind the API, and I highly recommend giving it a read.

With AbortController, it becomes trivial to cancel a request if it doesn’t resolve before a given period of time: if the abort method is called before the request resolves (or before the response Body is consumed), the request is cancelled; if it’s called after, the browser just ignores the call. To put it all together, we need to:

Create an instance of AbortController
Create a setTimeout function that calls the controller’s abort method
Pass the controller’s signal to fetch’s options object

Putting It All Together

First, because we’re basically writing a shim around fetch, I’m going to add an extra little perk. If the response doesn’t return in the 200 range (that is, if response.ok evaluates to false), we’re going to throw an error. We absolutely do not need to do this — we could just catch our timeout and the function would work the same (we actually don’t even need to do that). However, I always perform this check anyways, so this removes a lot of boilerplate code for me.

Anyways, here is my generic fetchWithTimeout function. It should work in any environment that supports fetch and AbortController.

const fetchWithTimeout = (uri, options = {}, time = 5000) => {
  // Lets set up our `AbortController`, and create a request options object
  // that includes the controller's `signal` to pass to `fetch`.
  const controller = new AbortController()
  const config = { ...options, signal: controller.signal }

  // Set a timeout limit for the request using `setTimeout`. If the body of this
  // timeout is reached before the request is completed, it will be cancelled.
  const timeout = setTimeout(() => {
    controller.abort()
  }, time)

  return fetch(uri, config)
    .then(response => {
      // Because _any_ response is considered a success to `fetch`,
      // we need to manually check that the response is in the 200 range.
      // This is typically how I handle that.
      if (!response.ok) {
        throw new Error(`${response.status}: ${response.statusText}`)
      }

      return response
    })
    .catch(error => {
      // When we abort our `fetch`, the controller conveniently throws a named
      // error, allowing us to handle them separately from other errors.
      if (error.name === 'AbortError') {
        throw new Error('Response timed out')
      }

      throw new Error(error.message)
    })
}

Using the function is fairly straightforward. Because we return fetch directly, we can use it in much the same way; the only change should be the addition of a third parameter (our time argument) and the extra error handling we discussed above.

// This example _always_ logs the error, because I'm telling httpstat.us to wait
// at least 1s before responding, but setting the timeout threshold to 500ms.
// Also, this could definitely be written in async/await if you preferred.
fetchWithTimeout(
  'https://httpstat.us/200?sleep=1000',
  { headers: { Accept: 'application/json' } },
  500
)
  .then(response => response.json())
  .then(json => {
    console.log(`This will never log out: ${json}`)
  })
  .catch(error => {
    console.error(error.message)
  })

That’s it. That’s the whole post. Though the snippet is ultimately pretty simple (it’s 20 lines without whitespace and comments) writing this provided me with three major benefits: it forced me to abstract the function to the most reusable version I could, it gave me an opportunity to research AbortController to make sure I knew exactly how it behaved, and it provided a place where I can come find this snippet in the future instead of rooting through old projects.

Functional-First Accordions

Alec Lomas — Sun, 30 Dec 2018 00:00:00 +0000

Update (December 2019):

In the year since I've wrote this, it's become increasingly clear that this is not a good method for building accordions. Beyond all the work it takes to make the thing functional (you know, the point of this post), Dave Rupert recently wrote a short post detailing the accessibility shortcomings of this approach. I share Dave's opinion that the web, as a platform, needs to bring some of these common controls to the table to ensure a consistent, accessible experience for all of its users.

There are few UI components encountered as frequently as the accordion. Even if you’re unfamiliar with the term, you’re familiar with the pattern: a string of text, sometimes accompanied by a button or icon, that reveals more content underneath when clicked. Thousands of developers and hundreds of UI frameworks have created accordions, often with their own rigid markup structures and (potentially bloated) JavaScript. But did you know that a perfectly functional accordion component ships with most modern browsers? Check this out:

This is my cool accordion

100% HTML, baby. #usetheplatform

That’s all HTML! The code looks like this:

<details>
  <summary>This is my cool accordion</summary>

  <p>100% HTML, baby. #usetheplatform</p>
</details>

The element that helps us achieve this marvel of modern engineering is called details (along with summary to set custom titles). It allows us to create content that is not visible until the element is clicked on. Sounds like an accordion to me!

Of course, there are some downsides to the details element. For starters, it isn’t exactly what I’d call attractive. There’s no way to animate content in and out, and no way to adjust the “twistie” (the triangle icon that indicates the component state). In addition, working in most modern browsers means that it doesn’t work in all modern browsers, not to mention legacy browsers. But, much like our UI framework-developing forebears, we can use some CSS & JavaScript to solve those issues, with the added benefit of an accordion that works when JavaScript (and even CSS!) is disabled.

The Beauty Is in the Details

The first and easiest changes we should make just involve making the element display consistently in all browsers.

details {
  display: block;
}
summary {
  display: list-item;
}

Similarly easy, though a little more opinionated, is changing the cursor to highlight that the element is interactive.

summary {
  cursor: pointer;
}

Now let’s get into the fun stuff. First up is changing the default twistie to be something closer to convention.

/* Hide the default twistie */
/* Spec-compliant: */
summary {
  list-style-type: none;
}
/* Non-standard: */
summary::-webkit-details-marker {
  display: none;
}

/* Display a more common one */
summary {
  position: relative;
  padding-right: 1.5rem;
}
summary::after {
  content: '+';
  position: absolute;
  top: calc(50% - 0.5em);
  right: 0;
}
details[open] summary::after {
  content: '-';
}

Here’s the accordion as it looks at this point:

Not bad for a few lines of CSS! There’s a few more changes I would make before calling this anything approaching good-looking, though.

details {
  border-bottom: 1px solid #eee;
  padding: 1rem;
}
:not(details) + details,
details:first-of-type {
  border-top: 1px solid #eee;
}

summary {
  margin-bottom: 0;
  font-weight: 700;
}
summary + * {
  margin-top: 1rem;
}

Now we’ve got a relatively attractive accordion component. We could stop now, and we would have a working component that, with a few tweaks, could be dropped onto almost any site and Just Work™️.

Enchanting Progressive Enhancement

We don’t want to be outdone by those UI frameworks of yore, though. So we’ll need to do a little more work to animate the content in and out. The base markup does have to be changed to be a little less clean, and we’ll need some new CSS.

<details>
  <summary>An updated details accordion</summary>

  <div class="content">
    <p>I'm some content!</p>
  </div>
</details>

.content {
  overflow-y: hidden;
  transition: all 0.4s ease;
}

.content.is-closed {
  max-height: 0;
  margin-top: 0;
  margin-bottom: 0;
  padding-top: 0;
  padding-bottom: 0;
  opacity: 0;
}

You may have noticed that we didn’t apply the is-closed class to the content in the markup. Since we’re using JS to trigger that class, and it hides the content, we only want to apply the class if JS is allowed to run on the page.

for (const content of document.querySelectorAll('details .content')) {
  content.classList.add('is-closed')
}

There’s one last piece we need to set into place before we can trigger the animation. When the element is closed, it has an applied max-height of 0. Since the auto declaration is not animatable, we’ll need to apply a defined max-height to the content when it’s open. For the smoothest possible animation, that max-height should be the same size as the content height. We can write a simple function to calculate this height and store it as an attribute on the content element.

const getContentHeight = node => {
  // Force node to display properly
  node.classList.remove('is-closed')
  // Calculate height and store it
  node.setAttribute('data-height', `${node.getBoundingClientRect().height}px`)
  // Reset node to initial state
  node.classList.add('is-closed')
}

Now that we’ve accounted for that wrinkle, we can handle interaction on the element. In a bit of premature optimization, we’ll delegate the event to the document.

document.addEventListener('click', event => {
  if (!event.target.closest('summary')) {
    return
  }

  event.preventDefault()
})

All we’ve told the browser at this point is “if the user has clicked a <summary> element, don’t do anything”. The default behavior associated with clicking a <summary> element is to set/remove the open attribute on its parent <details> element (the browser then knows to hide/show the content inside of <details> based on this attribute). The browser won’t wait for the content to animate out before hiding it, so we need to do that manually inside our handler. The code to do this is fairly straightforward, and boils down to toggling attributes and classes in a specific order at a specified time.

// Inside of our event handler
const accordion = event.target.closest('details')
const content = accordion.querySelector('.content')

// Handle closing
if (accordion.hasAttribute('open')) {
  // Animate content out
  content.style.removeProperty('max-height')
  content.classList.add('is-closed')
  // Wait for animation to finish, then remove the `open` attribute
  window.setTimeout(() => {
    accordion.removeAttribute('open')
  }, 400)
  // Exit handler
  return
}

// Handle opening
// Set the `open` attribute so the content will display
accordion.setAttribute('open', '')
// If our content does not have a calculated height, calculate it
if (!content.hasAttribute('data-height')) {
  getContentHeight(content)
}
// Wait a beat for the height to calculate, then animate content in
window.setTimeout(() => {
  content.style.maxHeight = content.getAttribute('data-height')
  content.classList.remove('is-closed')
}, 0)

Putting it all together gives us a fully functional, animated accordion component. And because we started with an HTML element that gives us our core functionality by default, a user doesn’t need to have JavaScript running to access the hidden content.

Extra Credit

Although the accordion we’ve created is great, we’ve only covered the baseline functionality. There are a few ways we can change or improve the functionality further, including but not limited to:

Improve Accessibility

Because the <details> element is baked-in to the platform, it should be accessible by default. However, this only applies to browsers that actually support the element. If you have users from browsers that don’t support the element, considerations for accessibility should be taken (adding tabindex and aria- attributes, for example).

Handle Window Resizing

The vertical expansion animation we’re using to transition accordion content in and out of view is smooth and natural, but there is one issue: it isn’t responsive. Because we only calculate the height of the element once, if the element width changes to the degree that the content flows to a new line, the animation will break. An ideal solution would account for this, and there are a variety of ways we could do so.

Increase Interaction Target Size

We set container padding on the <details> element to give the contents of the accordion room to breath. However, this means to open the accordion you have to click or tap on the <summary> content. Setting the padding on the <summary> and content container independently should make the accordion a little easier to use.

Animate the Twistie

Animating the twistie to compliment the content animation would bring another level of polish to our accordion. Extra extra credit: make the animation happen on interaction (instead of relying on the [open] attribute).

Force Content to Show In Non-Screen Environments

Accordions can bring a lot to the table in screen-based environments, however they can also make content inaccessible in non-screen environments (such as when printing or using a screenreader). The content should be accessible in all environments.

Only Open One Item At a Time

Just kidding. If you need an accordion at all, you probably should not do this. As it is an action not directly requested by the user, it can cause frustration.

Package the Accordion Into a Reusable Component

We should probably abstract away all of this markup to ensure consistency and improve DX. Frameworks like React and Vue provide a simple way to do this, but it should also be possible in most templating languages.