Matthew Roach

2021

2021-12-31T00:00:00Z

Well, a global pandemic

Not much changed from 2020. At times it felt like things were getting better, but as we all know that was short lived. Three vacinations received in 2021, how many will there be in 2022?

Some items that happened in what felt like a blur of a year, in no particular order -

👨‍💻 Started off the year by switching jobs after the move last year not working out as I expected
🚴 Bought a new road bike and enjoyed the early spring sun, even got Pamela out on the open roads a couple of times, even when there was no cake involved
🏖 Enjoyed a family holiday to Edinburgh that included my parents
🚘 Switched to an electric car, first a Vauxhall Corsa-e, then to an Volkswagen ID.3
🎉 Now a parent to a teenager
🏑 My son started playing field hockey for the men’s 2nd team
🏑 I started playing hockey again, after playing it when I was younger (20+ years ago). Been amazing being able to play alongside my son, and watch how fast he is progressing.
👩‍🎓 My wife finished her studies and started a new job with her qualifications

2022 - who knows what’s going to happen…

A Themeable Design System

2021-12-09T00:00:00Z

I've been involved with design systems for a good number of years. Even before design systems, there where styleguides. Remember those?

Design Systems, Styleguides, pattern libraries, etc. They are all great tools/systems and having created and consumed a variety of these systems over the years I've recently come up against a problem where the "traditional" systems where not flexible enough.

If you go look at any of the big tech companies desgin system(s) they have published you'll notice they are all aimed at the companies usage, which is great. If you are building an integration on top of shopify using their design system polaris to maintain consistency from your integration to shopify's application is great.

Even some big names provide "themes" on top of their systems. If the company has a few identities you are able to use the correct theme for the relevant company.

These are all great, but -

What if you wanted to provide as much flexibility as possible?

What if you didn't know who was going to using the system?

What if you wanted the ability for the system to be flexible enough to apply a companies own style to it?

These are just a few of the questions I was faced with answering recently. How can we provide a core set of components, that are ultimately fully customisable at the core? But also provide an "out-of-the-box" theme.

Based on these questions and more, I came up with following solution which I am going to walk you through.

Technology

For the solution as it is to be used in part of an exisiting ecosystem. The technology stack wasn't completely open. React was a hard requirment, the styling was a bit more open - it was either going to be a CSS-in-JS approach or CSS. I opted for CSS, but with Sass as the integration layer, and the end result being a standalone CSS file.

System Overview

The system is broken down to three parts

Theme
Components
Blocks

The core of the system is a set of components, think of these as the core. The components would be used as the building elements of blocks, example of such components -

Paragraph
Image
Caption
Date
Link

These components are very presentational, and are a means to provide a consistent interface to commonly used components of the system. The components are not limited to outputting text, images, etc, a component can also be a layout component.

Blocks are used within the system to provide an entry point and exit point. The entry point being the internal system, and the exit point being the published page. A block is a composed component of functionality that is made up primarily of components. An example of a block would be

Promo Item
List of articles
Search Results list

Theme the theme is what brings it all together and holds the styling information. The theme is a collection of Sass maps that hold the CSS properties and values for a component, a block and also the ability for component within a block to be styled.

System Breakdown

Components

To understand how it all fits together and what is involved at each level, I am going to run through a basic example.

The paragraph component looks as follows

import React from "react";
import PropTypes from "prop-types";

const Paragraph = ({ children }) => <p className="c-paragraph">{children}</p>;

Paragraph.propTypes = {
	children: PropTypes.string.isRequired,
};

export default Paragraph;

Very simple and basic React component that takes children and output wraps that in a p tag, where we apply a class of c-paragraph.

The class applied to the component is exposed via a Sass file which looks as follows

.c-paragraph {
	@include component-properties("paragraph");
}

This would the bare minimum for a component Sass file. It looks a little bare, and not doing anything at the moment. This is because the styling will come from the theme. We are using a mixin provided by the system that would output the CSS properties and values for a paragraph

Blocks

As mentioned earlier, blocks are composed of components. An very simple block could look like

import React from "react";
import PropTypes from "prop-types";

import { Paragraph } from "components";

const FakeStory = {
	description:
		"One of the highest paved roads in Europe, this mountain pass makes for a thrilling road trip into the misty mountains above the Adriatic and Ionian seas.",
};

const Promo = () => (
	<div className="b-promo">
		<Paragraph>{FakeStory.description}</Paragraph>
	</div>
);

export default Promo;

As you can see it's very basic. The promo block is only using a single component in this example, but it could use any number of the core components if needed. The block has a wrapping div with a class b-promo this is then exposed via a block Sass file to allow styling of the block but also components inside a block.

The Sass file for a block is as follows

.b-promo {
	@include block-components("promo");

	@include block-properties("promo");
}

Similar to components, we are making use of mixins to load in the promo block styles, but also load in the styles for components within a block. How the component styles work will be explained below as part of the theme.

Theme

The theme is where the styling is controlled for a component, a block and for components within a block.

The theme is utilising Sass to extend the capabilites of CSS by providing some mixins and better variable management. The output from the Sass files is a CSS file that is utilising CSS Variables. The primary reason to use Sass is the power it provides with being able to doing looping and provide functions (mixins).

Within the theme there are multiple Sass maps, following the design token approach it's broken down into four distinct areas

Global
Alias
Components
Blocks

Global

Global tokens are sets of tokens that are the core to the system. Color pallettes, font sizing, font weight, spacing, etc. Each token in the global tokens map is output as a CSS Variable prefixed with --global-.

$global: (
	"gray-50": rgb(218 218 218)
);

is then converted into the following CSS

:root {
	--global-gray-50: rgb(218 218 218);
}

Alias

Alias tokens are technically still global tokens, but provide the ability to have a friendly name attached to a given global token. For example, primary-color would be an alias token, and the value of that token would reference a global token. Each token in the alias map is output as a CSS variable - these are not prefixed at all.

$alias: (
	"primary-color": rgb(100 100 100)
);

is then converted into the following CSS

:root {
	--primary-color: rgb(100 100 100);
}

Components

Component and block tokens are a little different to the global and alias set up, as these are nested Sass maps that follow the CSS property, and value set up.

For components the nested Sass map is structured with the first key inside the map being a component name. If you remember from before there is a Sass mix that looks up the component tokens by name. Meaning the component name will need to match that which is set in the components .scss file.

$tokens: (
	components: (
		"paragraph": ()
	)
);

Then inside the paragraph map we have the ability to use CSS properties and values just as if you were writing CSS, allowing you do something like

'paragraph': (
	'font-size': 16px,
	'font-weight': bold,
),

If we bring back the code from above of how we write the Sass for the paragraph component we can see how they work together

.c-paragraph {
	@include component-properties("paragraph");
}

With the above code and the above example the generated CSS would be

.c-paragraph {
	font-size: 16px;
	font-weight: bold;
}

Obviously that's not great to use hard coded values as the value items in these maps as you loose the power of the token system. Knowing how the previous global and alias tokens are converted you can reference those as the values

'paragraph': (
	'font-size': var(--global-font-size-200),
	'font-weight': var(--global-font-weight-700),
),

this would then make use of the CSS variable in the outputting CSS as follows

:root {
	--c-paragraph-font-size: var(--global-font-size-200);
	--c-paragraph-font-weight: var(--global-font-weight-700);
}

.c-paragraph {
	font-size: var(--c-paragraph-font-size);
	font-weight: var(--c-paragraph-font-weight);
}

Blocks

The blocks part of the theme works in a similar way to components the @include block-properties('promo'); Sass mixing does pretty much the same as the component-properties version, the only difference is it's looking for the named item within the blocks map.

$tokens: (
	blocks: (
		"promo": ()
	)
);

The added ability you have within a block is the ability to change the style of a component differently to that of the base components styling. As we mentioned before blocks are composed of components, this means by default and using the CSS cascade all components will have the same styling when used within a block. But what if you want to make the paragraph component within the promo block to be styled slightly different? Say we wanted to increase the font-size thats where the Sass mixin @include block-components('promo'); comes in.

Given we have the need to update the paragraph font size within a promo block the blocks map has the ability for us to define component styles for a given block.

$tokens: (
	blocks: (
		'promo: (
			'components': (
				'paragraph': (
					'font-size': 18px,
				),
			),
		),
	),
);

To break down the nested map it can be a little easier read from the inside out. What the map is saying is for the paragraph component inside a block set the font-size to 18px. How this is translated to CSS is by using the power of CSS variables, as previously mentioned we are outputting to CSS variables at all times meaning that we are able redfined the paragraph font size CSS variable within the promo block CSS.

Reminder of how the block Sass file is

.b-promo {
	@include block-components("promo");

	@include block-properties("promo");
}

Based on the above example of setting the paragraph font-size to 18px within a promo block the CSS would be output as

.b-promo {
	--c-paragraph-font-size: 18px;
}

Working Examples

Code is available on GitHub - Theme Component Repo

It's all demo'd via storybook which is published - Theme Components Storybook

JAMStack URL Shortener with Netlify, 11ty and GitHub

2021-02-07T00:00:00Z

Why...

I wanted a place where I can "bookmark" things I come across on the internet. Either for reading later, sharing or to keep a record of it for future reference.

For the sharing part I wanted to a way to use a shortened style link

Also, I want to own all this data. Along with not having to maintain a web application.

What if I could do all this with static site generation tool 11ty, and Netlify?

How...

Well turns out it's very possible, and much easier than you might think.

Broken down into the following parts

Netlify to host the site and handle the URL redirection
Eleventy to handle the website output and redirect file
GitHub issues as a UI to add items
GitHub actions to handle adding the content from the issue to the site

And the output of all this is my own URL shortner/bookmark "application" - https://roach.link

Netlfiy

For the Netlify part it's very straight forward. The provide a way to host a site, and also a mechanism for handling redirects. Setting up a site is pretty straight forward from their UI with a few customisable options. For the redirect part as long as you have a _redirects file in the directory you want to serve your site from they take care of the rest. The also allow you have use a netlify.toml file.

Eleventy (11ty)

For the 11ty part I went for a very similar set up to my personal site (this site) set up. Each link would be a markdown file inside a posts directory that looks like this

---
title: "Matthew Roach"
date: "2021-01-24"
permalink: "b/view/"
link: "https://matthewroach.me"
tags: ["personal", "blog"]
---

Personal website of Matthew Roach

The frontmatter data is where the majority of the needed data is housed. You may notice the permalink seems a little odd why is it b/view? The b part is the URL shortner unique ID, and the view part is used to build the output for each post to be roach.link/b/view allowing you to view the individual bookmark item (single view page still work in progress).

Hang on.. You said unique ID... That's going to be fun to maintain I hear you ask. Well it would be if you were trying to do it by hand. But I am not, I am using an npm package called bijective-link-shortener to increment them each time. Which is handled with GitHub as you'll see later.

Redirect file

Without the ability to do redirection a URL shortner isn't much use, and as previously mentioned Netlfiy allows you to do redirects if you provide either a _redirects or netlify.toml file in the root of the published site. And with 11ty this is made super simple to generate, as with 11ty you can configure it to output the input file to any output file (give or take), by setting the permalink to be the output.

Given all the bookmarks are all going to be individual files in a folder I set up a new collection in the .eleventy.js config file named allLinks and reversed the collection so the newest would come first.

With a file named _redirects.11ty.js in my src directory I can consume the allLinks collection and make 11ty render out the links in a format needed for Netlify. The _redirects.11ty.js looks as follows

class Redirects {
	data() {
		return {
			permalink: "netlify.toml",
		};
	}

	render(data) {
		return data.collections.allLinks
			.map(
				(l) =>
					`
[[redirects]]
	from = "${l.url.split("/")[1]}" // permalink is in format {shortLink}/view
	to = "${l.data.link}"`
			)
			.join("");
	}
}

module.exports = Redirects;

Broken down the file is looping over the allLinks collection, and setting up the Netlify redirect file in the format they require by using the permalink data (first part) and the link from each posts frontmatter data. As as the permalink of this file is set to netlify.toml it will create that file based on the render method.

The output file looks as follows

[[redirects]]
	from = "b"
	to = "https://matthewroach.me"

GitHub

GitHub is where I am hosted the source code and then have Netlify linked to the repo to build the site and publish on each commit to the main branch.

Issues

But GitHub is also the primary way I add new data to the site. Rather than having to create a new file and fill in all the frontmater data, and do a host of git commands I wanted a way I could actually use this "application" with minimal effort. Turns out GitHub issues is a ~~great~~ perfectly acceptable way to be the UI for adding new bookmarks... That is if you are willing to make a small adjustment.

So, GitHub issues provides all but one of the interface items I needed. This is how I mapped the GitHub issue UI to the frontmatter data

Issue Comment = The post body
Labels = Tags
Title = Title and link

Title = title and link? That seems odd. Well turns out the issue UI doesn't really have a field or place I could enter the URL for the item I want to bookmark. So I went with the format of making the title as follows:

Matthew Roach Blog::https://matthewroach.me

The two colons has no meaning other than for when the GitHub action runs and splits the title using title.split('::') to parse it into two parts. The first part is the Title of the Site, and the second is then used in the link frontmatter data field.

Actions

GitHub actions is the glue that makes all the previous steps work together. Without actions the process of adding bookmarks would be very manual. Actions are a way for you to automate workflows from your GitHub repository. Based on an action you can configure an action to run and do "things". Those "things" are what makes this all possible.

As mentioned I am using GitHub issues as a UI to add new bookmarks. Broken down this works as follows

Issue
1. Add a new issue to my roach.link repository
2. Once I am happy with the description and tags
3. Mark the issue as closed
GitHub action runs on issue closed event
1. The action is triggered and starts its "steps"
2. Action checks out code, sets up node and makes the issue object available on an environment variable
3. Then a node command runs a script node new-item-from-issue.js 1. Within the script I have access to the issue object by doing JSON.parse(process.env.ISSUE_CONTEXT) 2. Script checks how many posts are currently in the posts folder, and using the package bijective-link-shortener gets the next short link value 3. Using the data from the issue object and the short link value from the previous step I use transformAndWriteToFile from the package json-to-frontmatter-markdown to create a new markdown file in the format noted above
4. Add and commit is then run from within the action to add the newly created file to the repo
Netlify is triggered due to a new commit on the main branch
1. Netlify runs its build steps I have configured
New version of site is live at https://roach.link
1. Homepage is updated
2. New redirect added - example: https://roach.link/b

VSCode focus between terminal and code

2021-01-30T00:00:00Z

I recently began to utilise the integrated terminal for VSCode more. And being a big fan of using my keyboard to switch around different parts is huge part of my work flows. One of my sticking points with the terminal in VSCode is by default you can not switch into and out of the terminal easily.

For example if I am editing some code, then need to switch to the terminal to run some commands, and then switch back to the code window. I got so used to using command + tab to switch windows. Wanting to try and use VSCode more it turns out this was a sticking point of my flow. With some digging and trial and error it turns out you can setting up a custom keybinding to handle this.

As there was already a default key binding to open a terminal, once opened you can not easily switch back. But with VSCode and key bindings you are able to use the when key to tell a key binding "when" something can be run. This allowed me to set the same key binding used to focus terminal as to focus back to the editor. Below is instructions and the key binding JSON to achieve this on a Mac.

Instructions for Mac

Code > Preferences > Keyboard Shortcuts
This opens a GUI for keyboard shortcuts - click on the tab "Keyboard Shortcuts", and an icon with a file and arrow will appear (title - Open Keyboard Shortcuts JSON)
Copy paste the below JSON into the file and save
Done

[
	{
		"key": "ctrl+`",
		"command": "workbench.action.terminal.focus"
	},
	{
		"key": "ctrl+`",
		"command": "workbench.action.focusActiveEditorGroup",
		"when": "terminalFocus"
	}
]

Another VSCode tip - VSCode zoom only font not whole editor.

Web Share API - Progressively enhanced web component

2021-01-24T00:00:00Z

How I implemented a share button at the bottom of my blog posts on this site using the Web Share API and web components. Scroll to the bottom and see if your browser supports the Web Share API... You'll see a share button.

Being able to hook into native functionality when its available is a great especially when you are able to do it in a progressively enhanced manner. A great example of this is the Web Share API. It is quite a new API that is still in working draft at the W3C. Even though it is still in working draft and not a common API available on all browsers. The main point is that it is available on some browsers. This allows you to start using it, and by allow the users of those devices and browsers to have an extra feature available to them. Aka - Progressive enhancement. While this allows you to use a new feature, its also a way for browsers and the W3C to get people testing the features, get excited and for it to become more than a working draft.

As with all technical web docs, a great starting point is MDN Web Docs, and the docs for the Web Share API is no different. The API is exposed to you via JavaScript as Navigator.share().

Broken down the Web Share API is one asynchronous method call, if its available in the users browsers. The function takes an object containing the data to share.

navigator.share({});

The data you pass to the function is

url - A URL string referring to a resource being shared
title - The title of the document being shared. May be ignored by the target
text - Arbitrary text that forms the body of the message being shared. (not used in my examples)
files - Files to be shared (not covered in this post)

In its most basic example you can just pass the url and title to the share() method and it will work for supported browsers. (Try copy and pasting the following into console of dev tools of a supported browser).

navigator.share({
	url: "http://matthewroach.me/web-share-api-progressively-enhanced-web-component/",
	title: "Web Share API - Progressively enhanced web component",
});

While this is all great and all, I've mentioned progressively enhanced quite a few times already, and that this API is not available in all browsers. Being able to implement this as an enhanced feature is very neat, and if you pair it with web components you can have a fully isolated and truly enhanced feature for some of your users. Web components (customElements) pairs well here as they are available in the browsers that have support for the Web Share API.

The button

We are dealing with an action, so we use a button, and as the button should only be shown if the browser supports the Web Share API its default state is hidden. As the Web Share API is a JavaScript based API and we can only detect it in the users browser we will control the visibility of the button via JavaScript. This also means if you are browsing without JavaScript enabled you are none the wiser.

<button
	hidden
	is="s-hare"
	a-title="Web Share API - Progressively enhanced web component"
	a-url="http://matthewroach.me/web-share-api-progressively-enhanced-web-component/"
>
	Share
</button>

You maybe wondering what the extra attributes on the button are. the is and the a-title and a-url are.

The is global HTML attribute: Allows you to specify that a standard HTML element should behave like a registered custom built-in element.
The a-title and a-url are custom attributes I decided to use for the component to read them for when the share API is called. Remember from above to share you need a url and title passed to the method.

The JavaScript

All the code that makes the button.. Pop.. Or well work in situations where it is able to. The progressive enhanced experience.

Below is the full JavaScript class and custom element define call to set up the button code from above to work.. Side note, view source to see it on my site.

As I used the is attribute on the button element our class extends the HTMLButtonElement

In the constructor I call a class method canWebShare - if this returns false. Browsers that don't support the Web Share API nothing more happens. But if your browsers has the Web Share API available navigator.share, the code will call showButton which actually shows the button and adds a click event listener to it.

Accessibility Tip: As I have extended the native HTML button you only need to set up the click event as the button element will fire this event when the user uses either the enter or space key on their keyboard. It will also catch the mouse click event too.

Now the event listener is added the button is all set for user interaction, and this is where the a-title and a-url attributes come into play. When a user activates the button the event listener function will use the values of these attributes to pass the data to the navigator.share method. Remember this method call returns a promise, you can use await here.. And guess what no need to polyfil for this as the browsers that support Web Share also support await

The share dialog is part of the users operating system (OS) and from when the user clicks the button you have passed the share off to the OS.

class Share extends HTMLButtonElement {
	constructor() {
		// Always call super first in constructor
		self = super();

		if (this.canWebShare()) {
			this.showButton();
		}
	}

	canWebShare() {
		return navigator.share !== undefined;
	}

	showButton() {
		self.removeAttribute("hidden");
		self.addEventListener("click", self.shareEvent);
	}

	async shareEvent() {
		try {
			await navigator.share(self.shareData());
		} catch (err) {
			alert("Sorry, sharing failed - you could try again");
		}
	}

	shareData() {
		const shareData = {
			title: self.getAttribute("a-title"),
			url: self.getAttribute("a-url") || window.location.href,
		};

		if (self.getAttribute("a-text")) {
			shareData.text = self.getAttribute("a-text");
		}

		return shareData;
	}
}

customElements.define("s-hare", Share, { extends: "button" });