Forem: Stuart Jones

Anchoring elements in scrollable areas

Stuart Jones — Wed, 31 Aug 2022 05:13:11 +0000

The other day I wanted to place an element into a scrollable container that would stay anchored near the bottom of the container as the user scrolled the rest of the content.

I thought that you could do this with absolute positioning:

As you can see - the "anchored" bar still moves as the user scrolls, even though the bar starts where we want it to.

My mental model was wrong - I was thinking that the anchored item would be positioned relative to the bounding box around the scrollable content. It isn't.
The item starts positioned relative to the bounding box - but it will keep its position relative to the parent (which scrolls within the bounding box), so it scrolls, too.

To make better sense of this, think about what would happen if you set overflow to visible instead of auto.
The absolutely positioned element in the container will be anchored to the container - but the content will continue on down. As you scroll the whole page down, the absolutely positioned element will keep its place relative to the rest of the content.

Relative vs absolute positioning

Relative positioning is used to place an element relative to where it would normally be in the flow if left alone.

Absolute positioning places an element relative to the top-left corner of the nearest parent that is not positioned statically. Static positioning is the default.

Contain yourself

I reached out to the Perth Fenders community, who are some really awesome developers and designers. One solution from Pete Barr involves using some additional containers:

The only problem here is that the scrollbar is obscured slightly by the anchored element - though this could probably be resolved with a bit more refinement.

Getting sticky with it

I also had a try at using sticky positioning. This has been around for a few years, but only received broad support in early 2021 (Chrome and Edge were the holdouts).

If you have something with position: sticky and top: 0, it will appear as you scroll up with the rest of the content, but as you scroll past the sticky element it will now sit at the top.

Similarly, bottom: 0 will have it sit at the bottom until you scroll past where it would be in the flow.

I anchor the element from the top of the container with top: calc(100% - 3rem); to ensure it stays where I want it. Unfortunately, I couldn't position it relative to the bottom, because there might not be enough other content in the container to make sure it always stays anchored down there.

But this solution itself creates a problem - there is now a gap at the top of the content which was the same size as the anchored item.

We can fix this with a height fix:

Refinement

The above code works for when there's one line of text in the anchored element - but what about when we don't know how much text will be in there? It would just overflow down out of the viewable area.

Absolute position to the rescue!

So, our zero-height anchored element is stuck to the bottom of the viewable area - and its contents are absolutely positioned relative to the anchored element, so it grows up the page and not down.

Side-scrolling adventure

As I was about to write all this, I saw a tweet by Dries Vints describing a similar problem, but in the horizontal axis. He was looking to have a button or toolbar sit over on the top right of a preformatted code example.

Because the <pre> element uses preformatted space, we need to insert the toolbar on a single line with not whitespace, otherwise the sample code will have a margin above and below.

Other than that, we can see that we've stuck the toolbar to the top right of the scrollable container, and in a way that would allow use to easily insert multiple buttons without having to change the positioning.

Making Web Components reactive

Stuart Jones — Tue, 19 Apr 2022 02:37:07 +0000

Welcome to part 3 on my experiments with creating native and light-weight, accessible and stylable Web Components.

This part is all about making our Web Component reactive, and working with that reactivity in a vanilla application, and
also in modern frameworks such as Vue.js and React.

What is reactivity?

If you've ever used a calculation in a spreadsheet to sum several rows of data, and then modified one of those rows, you
will have seen the calculated value immediately updated. The calculation is reacting to the change in inputs. As you
change the input, a signal informs the spreadsheet the input has changed, the spreadsheet then informs any calculations
that are using that input what the new value is, and the calculation is updated.

Similarly, if a web application has a toggle to change from light mode to dark mode, an event is fired when the toggle
is clicked on by the user. The event information usually includes the updated state of the toggle, and is
used by the application to inform the various parts of the application that need to know whether the user is in light or
dark mode, so that they can react accordingly.

For a Web Component such as the dropdown selector I've been building throughout this series to be useful, we need to be
able to read its properties and attributes, and detect when changes have been made so other parts of
the web application using the Web Component can react appropriately. Sometimes we may want the component to react to
events and data from other parts of the application.

First things first

As I work through making the dropdown-selector reactive in this article, I'm going to show examples of its use in
vanilla, Vue.js, and React.

Here's a quick run through on getting the (non-reactive) Web Component working in these three environments.

One thing that is common to all is how we define our custom element:

class DropdownSelector extends HTMLElement {
  constructor() {
    super()
      .attachShadow({mode: 'open'})
      .innerHTML = '<div>...</div>';
  }

  connectedCallback() {
    // stuff to do when <dropdown-selector> is added to the DOM and rendered
  }

  // all the rest of the API and behaviour of our element
}

// make the browser aware of our custom element and have it load in the component when we use <dropdown-selector>
customElements.define('dropdown-selector', DropdownSelector);

Vanilla

Almost all modern and evergreen browsers allow the use of Web Components (with some caveats)
without any additional tooling or polyfills.

As covered in the previous parts, once we have defined our element, we can place it anywhere inside our HTML document:

<form>
    <label for="select-month">Choose a month</label>
    <dropdown-selector id="select-month">
        <option>January</option>
        <option>February</option>
    </dropdown-selector>
</form>

Vue.js

Vue brings a little complexity - the newer version of Vue automatically resolves non-native HTML tags, and will emit a
warning if it can't resolve the tag to a Vue component.

To overcome this, we can add a hook into the compiler options
to skip resolving certain tags. However, I find the example in the
documentation to be a bit simplistic, especially as I've gotten into the habit of using kebab style tag names for my Vue
components over the last few years.

You can either list each custom element you're importing:

// vite.config.js or vue.config.js

compilerOptions: {
  // list all custom-elements
  isCustomElement: (tag) => [
    'dropdown-selector',
    // additional elements
  ].includes(tag)
}

Or, you can use a prefix:

// vite.config.js or vue.config.js

compilerOptions: {
  // list all custom-elements
  isCustomElement: (tag) => tag.startsWith('awesome-')
}

This would require that you change the custom element definition:

customElements.define('awesome-dropdown-selector', DropdownSelector);

<template>
    <form>
        <label for="select-month">Choose a month</label>
        <awesome-dropdown-selector id="select-month">
            <option>January</option>
            <option>February</option>
        </awesome-dropdown-selector>
    </form>
</template>

To ensure correct behaviour right from loading the page, define the custom element before you create the App in main.js:

customElements.define('dropdown-selector', DropdownSelector)

createApp(App).mount('#app')

React

Using the custom element in React is much the same as in vanilla - with the usual allowance for React's syntax:

<form>
  <label htmlFor="select-month">Choose a month</label>
  <dropdown-selector id="select-month">
    <option>January</option>
    <option>February</option>
  </dropdown-selector>
</form>

As with Vue, make sure you define the custom element before rendering the App in main.jsx:

customElements.define('dropdown-selector', DropdownSelector)

ReactDOM.render(
        <React.StrictMode>
          <App />
        </React.StrictMode>,
        document.getElementById('root')
)

Web Component events

As it turns out, having our dropdown selector inform the rest of the application of when a user has changed the
selection is the easy part.

The first step is to add this to the select method in our selector, which
will trigger an event whenever the selected value changes in the dropdown:

select(index)
{
  //...

  if (this.__value !== this.__initialValue) {
    this.dispatchEvent(
            new Event('change')
    );
  }
}

Because we are dispatching the event from the dropdown selector itself (this), the event target will point to the
selector and allow us to access its current state.

Now, if we want to update another part of our page (or send the value in an API request, or anything really), we need to
listen for the change and react to that information.

Vanilla

If we have an output in our document that we want to update whenever the selector's value changes:

<p id="selected-month" role="status">January</p>

We can listen for the change in our dropdown and update the output:

document.getElementById('select-month').addEventListener('change', (event) => {
  document.getElementById('selected-month').innerText = event.target.value;
});

Vue.js

In Vue, we can define a reactive variable to store the output:

const selectedMonth = ref('January');

Now we can add a listener to the selector which updates the selectedMonth:

<form>
    <label for="select-month">Choose a month</label>
    <dropdown-selector @change="(event) => selectedMonth = event.target.value">
        <option>January</option>
        <option>February</option>
    </dropdown-selector>
</form>

<p role="status">@{{ selectedMonth }}</p>

React

Unfortunately, the onChange listener that we would normally use in React doesn't fire when the dropdown selector
dispatches the event.

We can fix this by using useLayoutEffect to add a custom listener:

import {useLayoutEffect, useRef, useState} from 'react';

function App() {
  const [output, setOutput] = useState('January');

  const selectorRef = useRef();

  useLayoutEffect(() => {
    const {current} = selectorRef;

    current.addEventListener('change', (event) => {
        setOutput(event.target.value)
      }
    );
  });

  return (
    <div>
      <label htmlFor="dropdown-selector">Pick a month</label>
      <dropdown-selector id="dropdown-selector"
                         ref={selectorRef}
      >
        <option>January</option>
        <option>February</option>
      </dropdown-selector>
    </div>
  )
}

Changing things up and taking control

So, getting the value from the dropdown when the user selects a new option is relatively straightforward. But what about
when we want to take control of it instead.

There's quite a few things that can change here:

The list of options - think about a pair of inputs where the options in the second one change depending on what you select in the first. An example of this is when picking a car manufacturer and then a model made by that manufacturer;
The label - depending on what is actually in the dropdown list, we might want to modify the label to better inform the user what the choice being offered represents;
Disabling the dropdown - again with the car manufacturer/model example, you might want the model selector disabled until the user has specified a manufacturer;
Setting which option is selected;
Restyling the dropdown - perhaps changing the border to indicate an error of some kind.

Disabling the dropdown

In native HTML, a form input is disabled by setting a boolean attribute:

<select disabled>
</select>

The browser will then ignore clicks, and will also try to apply some styling that indicates a disabled state. You can
also target the disabled element with CSS to apply your own styles.

We want the same kind of behaviour for our dropdown:

<form>
    <label for="select-month">Choose a month</label>
    <dropdown-selector id="select-month" disabled>
        <option>January</option>
        <option>February</option>
    </dropdown-selector>
</form>

We need to add a few lines of code to the DropdownSelector:

export class DropdownSelector extends HTMLElement {
  static get observedAttributes() {
    return ['disabled'];
  }

  // ...

  connectedCallback() {
    if (this.isConnected) {
      // ...

      // we need to store whether the user has defined a tabIndex for later use
      this.__userTabIndex = this.tabIndex; 

      // ...

      // click = mousedown + mouseup
      // browsers set focus on mousedown
      this.__combobox.addEventListener('mousedown', this.mousedown.bind(this));

      // ...
    }
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'disabled') {
      if (newValue !== null) {
        // prevent focus from keyboard navigation
        this.tabIndex = '-1';
      } else {
        // restore the original tabIndex as set by the user
        // if the user didn't set a tabIndex, this will remove the tabIndex
        this.tabIndex = this.__userTabIndex;
      }
    }
  }

  disconnectedCallback() {
    // ...

    this.__combobox.removeEventListener('mousedown', this.mousedown.bind(this));

    // ...
  }

  // ...

  click(event) {
    if (this.disabled) {
      return;
    }

    this.__open ? this.closeList() : this.openList();
  }

  // ...

  mousedown(event) {
    if (this.disabled) {
      // stops the element getting focus when clicked
      event.stopImmediatePropagation();
      event.preventDefault();
    }
  }

  // ...

  get disabled() {
    // boolean attributes have no value - they either exist or they don't
    return this.hasAttribute('disabled');
  }

  set disabled(newValue) {
    if (newValue) {
      // boolean attributes have no value - they either exist or they don't
      this.setAttribute('disabled', '');
    } else {
      this.removeAttribute('disabled');
    }
  }

  // ...

  get tabIndex() {
    return this.getAttribute('tabIndex');
  }

  set tabIndex(newValue) {
    if (newValue) {
      this.setAttribute('tabIndex', newValue);
    } else {
      this.removeAttribute('tabIndex');
    }
  }

  // ...
}

Let's break this down:

// ...

static get observedAttributes() {
  return ['disabled'];
}

// ...

connectedCallback() {
  if (this.isConnected) {
    // ...

    // we need to store whether the user has defined a tabIndex for later use
    this.__userTabIndex = this.tabIndex;

    // ...
  }
}

// ...

attributeChangedCallback(name, oldValue, newValue) {
  if (name === 'disabled') {
    if (newValue !== null) {
      // prevent focus from keyboard navigation
      this.tabIndex = '-1';
    } else {
      // restore the original tabIndex as set by the user
      // if the user didn't set a tabIndex, this will remove the tabIndex
      this.tabIndex = this.__userTabIndex;
    }
  }
}

// ...

This tells our component to listen for changes to the disabled attribute - and then tells it what to do when it does change.

We want to prevent the user from being able to focus this element, so we need to set the tabIndex to -1 to remove it from the tab order.
When the element is re-enabled, we need to restore the original tabIndex value, or remove it if the user didn't set it).

// ...

// click = mousedown + mouseup - browsers focus on mousedown
this.__combobox.addEventListener('mousedown', this.mousedown.bind(this));

// ...

this.__combobox.removeEventListener('mousedown', this.mousedown.bind(this));

// ...

click(event) {
  if (this.disabled) {
    return;
  }

  this.__open ? this.closeList() : this.openList();
}

// ...

mousedown(event) {
  if (this.disabled) {
    // stops the element getting focus when clicked
    event.stopImmediatePropagation();
    event.preventDefault();
  }
}

// ...

When you click, the browser will also fire two other events: a mousedown and a mouseup.
This allows clicks to be interrupted/cancelled (when you press the mouse button down, then move it away from the element you were pointing at before releasing the mouse, nothing will happen).

While we want to open the list when clicking (or block it from being opened if the element is disabled), we also want to prevent the disabled element from ever getting focus.
Browsers set focus in reaction to a mousedown event, so we need to listen for it and stop the default behaviour as well as the immediate propagation on the event loop for this event.

Of course, we also clean up the event listener should the dropdown selector be removed from the document.

// ...

get disabled() {
  // boolean attributes have no value - they either exist or they don't
  return this.hasAttribute('disabled');
}

set disabled(newValue) {
  if (newValue) {
    // boolean attributes have no value - they either exist or they don't
    this.setAttribute('disabled', '');
  } else {
    this.removeAttribute('disabled');
  }
}

// ...

get tabIndex() {
  return this.getAttribute('tabIndex');
}

set tabIndex(newValue) {
  if (newValue) {
    this.setAttribute('tabIndex', newValue);
  } else {
    this.removeAttribute('tabIndex');
  }
}

// ...

These getters and setters allow us to reflect the properties and attributes of our component.
This means that whenever the disabled attribute is changed from outside the component, the internal property is correct, and vice versa.

Vanilla

In vanilla JavaScript, we can disable or enable our dropdown in the same way as any other element:

// this will disable the element
document.getElementById('select-month').setAttribute('disabled', '');

// this will enable it again
document.getElementById('select-month').removeAttribute('enabled');

If you want the dropdown to be disabled when the page loads, then set the attribute in the markup.
It can then be removed later using JavaScript.

<dropdown-selector id="select-month" disabled>

Vue.js

With Vue, you can bind the disabled attribute to a reactive boolean value or prop:

<dropdown-selector :disabled="disableSelectMonth">

Vue will handle the presence of the disabled attribute appropriately when disableSelectMonth is false.

React

On the other hand, doing this in React:

<dropdown-selector disabled={disableSelectMonth}>

Will cause the HTML to render as:

<dropdown-selector id="select-month" disabled="false">

The HTML standard for boolean attributes is that if the attribute exists (even as disabled="false" or disabled=""), then it is to be evaluated as true.
So, counterintuitively, an element marked as disabled="false" is disabled.

To prevent React outputting the incorrect markup:

<dropdown-selector id="select-month" disabled={disableSelectMonth ? '' : null}>

There is a bug report for this on GitHub.

Reactive label

Back in Making Web Components accessible, we pulled in a copy of the user's label so we could properly associate it using ARIA attributes within our component and provide a good accessible experience.

But what if the user wants to change the label after we've rendered the component already?

This is where another powerful browser API comes into play - the MutationObserver. With this API, we can watch for changes in the DOM and react accordingly.

Because of the length of code to manage the labels in our component, I've separated it from the connectedCallback method since the post on accessible components, and put in some work to allow for more general use:

attachLabelForAria(labelledElements) {
  if (!this.id) {
    return;
  }

  this.__parentLabel = document.querySelector(`[for=${this.id}]`);
  if (this.__parentLabel) {
    this.__label = document.createElement('label');
    this.__label.setAttribute('id', 'label');
    this.__label.textContent = this.__parentLabel.textContent;

    this.shadowRoot.appendChild(this.__label);

    labelledElements.forEach((element) => {
      element.setAttribute('aria-labelledby', 'label');
    });

    this.__parentLabel.addEventListener('click', this.click.bind(this));

    const style = document.createElement('style');
    style.textContent = '#label { position: absolute; left: -1000px}';

    this.shadowRoot.appendChild(style);

    this.__labelObserver = new MutationObserver((changes) => {
      if (changes[0]?.target === this.__parentLabel) {
        this.__label.textContent = this.__parentLabel.textContent;
      }
    });
    this.__labelObserver.observe(this.__parentLabel, { childList: true });
  }
}

The accessibility and styling concerns in this method are pretty much the same as in the other post, so I won't repeat myself here.

What we're interested in is picking up on changes to the label in the DOM and updating our label accordingly within our Shadow DOM:

this.__labelObserver = new MutationObserver((changes) => {
  if (changes[0]?.target === this.__parentLabel) {
    this.__label.textContent = this.__parentLabel.textContent;
  }
});
this.__labelObserver.observe(this.__parentLabel, { childList: true });

Here, we create an observer which watches for changes on the outer DOM label.
Since all we're interested in is the text content, we only need to observe for changes to the immediate children of the label ({ childList: true }).

We do need to ensure we clean up the observer if the dropdown is removed from the DOM, so we add this to the disconnectedCallback method:

this.__labelObserver.disconnect();

Vanilla

<form>
    <label id="label-for-select-month" for="select-month">Choose a month</label>
    <dropdown-selector id="select-month">
        <option>January</option>
        <option>February</option>
    </dropdown-selector>
</form>

document.getElementById('label-for-select-month').innerText = "Pick a date";

Vue.js

<form>
    <label for="select-month">@{{ labelForSelectMonth }}</label>
    <dropdown-selector id="select-month">
        <option>January</option>
        <option>February</option>
    </dropdown-selector>
</form>

React

<form>
    <label for="select-month">{labelForSelectMonth}</label>
    <dropdown-selector id="select-month">
        <option>January</option>
        <option>February</option>
    </dropdown-selector>
</form>

Reactive options

We've already used a MutationObserver on our label, and we can use another one to react to changes to the dropdown's collection of options.

Firstly, I've extracted the code that handles creating our component's listbox into its own method - it needs to be called when we first render the dropdown (from connectedCallback) and whenever the options change:

__extractOptions() {
  // reset the current state and remove existing options from our component
  // this will also remove any event listeners currently attached to each option
  this.__selectedIndex = 0;
  [...this.__listbox.children].forEach((element) => {
    element.remove();
  });

  // build from options that are in the dropdown-selector element in the DOM
  this.__options = [...this.querySelectorAll('option')].map((option, index) => {
    if (option.hasAttribute('selected')) {
      this.__selectedIndex = index;
    }

    const element = document.createElement('div');
    element.textContent = option.textContent;
    element.classList.add('option');
    element.setAttribute('id', `option-${index}`);
    element.setAttribute('role', 'option');
    element.setAttribute('aria-selected', 'false');
    if (option.hasAttribute('selected')) {
      element.setAttribute('aria-selected', 'true');
    }

    this.__listbox.appendChild(element);

    return {
      label: option.textContent,
      selected: option.hasAttribute('selected'),
      value: option.getAttribute('value') ?? option.textContent,
    }
  });

  if (this.__options[0]) {
    this.__combobox.textContent = this.__options[this.__selectedIndex].label
    this.__value = this.__options[this.__selectedIndex].value;
  }

  [...this.__listbox.children].forEach((element, index) => {
    element.addEventListener('click', (event) => {
      event.stopPropagation();
      this.select(index);
      this.click(event);
    });
    element.addEventListener('mousedown', this.__setIgnoreBlur.bind(this));
  });
}

Now we just need to set up our MutationObserver:

connectedCallback() {
//...
  this.__optionsObserver = new MutationObserver((changes) => {
    this.__extractOptions();
  });
  this.__optionsObserver.observe(this, {childList: true});
//...
}

//...

disconnectedCallback() {
  //...

  this.__optionsObserver.disconnect();
}

We're only interested in changes to direct children of the dropdown-select element, which is why were only observing the child list.

The wonderful thing about the MutationObserver is that it only checks for changes once each time the event loop ticks. We can make a lot of different changes to our options, and they will be applied all at once at the next tick.

Vanilla

We can modify the HTML inside the dropdown-select like so:

document.getElementById('select-month').innerHTML('<option>January</option><option>April</option><option>July</option><option>October</option>');

Vue.js

We can do conditional rendering and even looping over a reactive or computed array:

<dropdown-selector id="dropdown-selector">
  <option v-if="extraMonth" value="-1">Last December</option>
  <option v-for="(month, index) in monthList" :value="month" :key="index">@{{ months[month] }}</option>
</dropdown-selector>

React

Again, we can do conditional rendering and looping:

<dropdown-selector id="dropdown-selector">
  { extraMonth && <option value="-1">Last December</option> }
  { [...Array(numMonths).keys()].map((m) => (
      <option value={m} key={m}>{months[m]}</option>
  ))}
</dropdown-selector>

Changing the selected option

Typically, we want the user to select an option through the dropdown. But what if the developer wants to change the selection programatically?

The native HTML Select lets you change the selection via the value property. We can add a getter and setter to our dropdown component to do the same:

get value() {
  return this.__value;
}

set value(newValue) {
  // value is always a string because it's taken from an attribute
  // newValue might be a number, though
  this.select(this.__options?.findIndex((option) => option.value == newValue));
}

Vanilla

document.getElementById('select-month').value('January');

Vue.js

<dropdown-selector :value="selectedValue">
    <option>January</option>
</dropdown-selector>

Or if we want two-way binding:

<dropdown-selector v-model="selectedValue">
    <option>January</option>
</dropdown-selector>

React

To allow React to set the value from a reactive property, we need to tweak the component a little:

static get observedAttributes() {
  return ['disabled', 'value'];
}

//...

attributeChangedCallback(name, oldValue, newValue) {
  //...

  if (name === 'value') {
    this.value = newValue;
  }
}

Reacting to changes in the stylesheet

This post is getting to be quite long, and properly handling changes to styles and the stylesheet is going to be quite involved. I'm not sure when I'll follow up on it, either, I'm afraid.

So what next?

I've really been enjoying this dive into Web Components, pushing at their boundaries and experimenting with improving their accessibility and stylability, while also keeping a good developer experience.

For now, I'm going to work on refining these concepts and start building an open source library of Accessible Web Components, but I hope to learn more and write further posts as I go along.

Making Web Components stylable

Stuart Jones — Tue, 29 Mar 2022 04:51:22 +0000

Last month I started working on building accessible Web Components. This is part of a longer term project to produce accessible and stylable Web Components that require minimal build tools and dependencies, and also provide a similar developer experience to working with regular elements.

Since then, and in between other work, I've been looking at the current state of styling Web Components.

The problem of styling is actually caused by one of the features of working with Web Components, which use the Shadow DOM. This acts like a container which limits scripting and styling crossing over between the regular DOM and the Web Component - allowing Web Components to be discrete units that can be placed in any project. Unfortunately, this means that the ability for developers trying to include Web Components into their project have very limited style control.

On the other hand, while we want to allow developers using Web Components to have style control, we need to be careful to let that kind of control be deliberate and not just have an external stylesheet run roughshod over the considered design of the component.

So, what is the current state of styling Web Components, and how can it be done?

The reading

Web Components were introduced in 2011, but general support for them took a while. Over time, the approaches available to style them has shifted and evolved.

Smashing Magazine wrote about the various approaches available in 2016.
CSS Tricks have written a couple of articles, too, with the most recent in January 2021 (although it was updated in December).
Some other good reads are this explainer on CSS Shadow ::part and ::theme and a blog post by Nolan Lawson.

The first simple/naive attempt - failure

One of my objectives was to create the least amount of friction for developers using Web Components.

In my earlier blog post, I wrote about how I designed the <dropdown-selector> to work similar to a native <select>, particularly with how options were added to the element.

<dropdown-selector>
    <option>First choice</option>
</dropdown-selector>

Because I discovered that the contents of <dropdown-selector> were replaced by the component's own HTML and therefore weren't rendered, I thought that I could maybe do a similar thing with the <style> element and pull it in like I had with the <option> elements:

<dropdown-selector>
    <option>First choice</option>

    <style>
        * {
          background-color: #ccffcc;  
        }
    </style>
</dropdown-selector>

Unfortunately, the styles were applied to everything outside of the Web Component.

(Ab)using the media selector for success

After spending quite a big longer reading, thinking, working on other stuff, and just avoiding coming back to the problem, I suddenly had an idea. There is a way to create styles that are not applied, except in specific circumstances, and developers and designers use it all the time.

The media selector - <style media="print"> or @media print, for example. I freshened up on the @media rule and, while I wasn't sure it was a good idea, it didn't seem that there was anything specifically saying I couldn't do what I had thought of.

Basically, the idea came to me that I could do something like:

<style media="dropdown-selector">
    * {
        background-color: #ccffcc;
    }
</style>

Or:

@media dropdown-selector {
  * {
    background-color: #ccffcc;
  }
}

The tricky bit was then how to inject those styles into the element.

CSSOM - the CSS Object Model

Just as there is a DOM api which lets us access and modify the HTML in a document through JavaScript, there is something known as the CSSOM.

When working with Web Components that are using an open Shadow DOM, we can access the parent document's CSSOM in much the same way I had already accessed its DOM to pull in the dropdown's options.

Array.from(document.styleSheets).forEach((outerStyleSheet) => {
  if (Array.from(outerStyleSheet.media).includes('dropdown-selector')) {
    const styleSheet = document.createElement('style');
    this.shadowRoot.appendChild(styleSheet);

    Array.from(outerStyleSheet.cssRules).forEach((cssRule) => {
      styleSheet.sheet.insertRule(cssRule.cssText);
    });

    return;
  }

  if (Array.from(outerStyleSheet.cssRules).find((cssRule) => {
    return cssRule.media && Array.from(cssRule.media).includes('dropdown-selector');
  })) {
    const styleSheet = document.createElement('style');
    this.shadowRoot.appendChild(styleSheet);

    Array.from(outerStyleSheet.cssRules).forEach((cssRule) => {
      if (cssRule.media && Array.from(cssRule.media).includes('dropdown-selector')) {
        Array.from(cssRule.cssRules).forEach((cssRule) => {
          styleSheet.sheet.insertRule(cssRule.cssText);
        });
      }
    });
  }
});

Every <style> element in the document is accessible in the list under document.styleSheets, and each of those stylesheets has a media property which itself is a list which we can then look at to see if we are applying the styles to our dropdown.

When we find a stylesheet with the correct media property, we copy the rules from the original stylesheet into a new <style> element which we append to our component's Shadow DOM.

I also put in code to search for whenever an @media rule had been used within any stylesheet and copy the rules wrapped within.

This was working - I could now apply any styles to override the original built-in styles of the component. However, I wasn't particular keen on this use of the media selector - the browser itself wasn't complaining, and it was working, but it just didn't sit right.

On the other hand, the day was ending and it was time for dinner. So I committed the code as a proof of concept, and left it there.

The obvious in hindsight solution

Taking a step back and doing something else is a super-power for developers. Because, even if you're not actively thinking about the problem, your brain can put it into some kind of background process. Later, under the right conditions, a new perspective can bubble up.

So at about midnight, just as I'd laid my bedside book down and turned out the lamp, I realised that I didn't need the media selector at all. There was another perfectly acceptable solution that didn't require developers to use any tricky syntax, and didn't require the abuse of existing HTML/CSS attributes.

We are adding a new custom element, named 'dropdown-selector'. CSS could use that as a selector:

dropdown-selector * {
  background-color: #ccffcc;
}

We could then look for CSS rules that include that as a selector:

Array.from(document.styleSheets).forEach((outerStyleSheet) => {
  Array.from(outerStyleSheet.cssRules).forEach((cssRule) => {
    if (cssRule.selectorText && cssRule.selectorText.startsWith('dropdown-selector')) {
      const rule = cssRule.cssText.replace('dropdown-selector ', '');

      styleSheet.sheet.insertRule(rule);
    }
  });
});

This has the advantage of simplifying what we were doing before.

Specific styling with class and ID selectors

The above solution works fine if developers/designers want to apply general styles to all dropdown-selectors. But what if they want to target specific styles with a class or ID selector?

<dropdown-selector id="months" class="groovy funky">

</dropdown-selector>

ID selector

This is the easier of the two.

Given the element has an ID of months, we can pull out any rules that use #months in the selector. The only thing we have to do is replace #months with a selector that matches the root element in our component's Shadow DOM:

Array.from(document.styleSheets).forEach((outerStyleSheet) => {
  Array.from(outerStyleSheet.cssRules).forEach((cssRule) => {
    // ...

    if (this.id && cssRule.selectorText.startsWith(`#${this.id}`)) {
      const rule = cssRule.cssText.replace(`#${this.id} `, '#root ');

      styleSheet.sheet.insertRule(rule);
    }
  });
});

So, styles that select the dropdown by ID will apply, and in a way that maintains specificity:

#months {
  background-color: #ccccff;
}

Class selector

While the ID selector is relatively simple to implement, because it is a single and (hopefully) unique value, class selectors are going to be trickier. Elements can belong to multiple classes. Class selectors can also stack .this.that.

First, we'll copy the classes across from the dropdown-selector element:

Array.from(this.classList).forEach((cssClass) => {
  this.__root.classList.add(cssClass);
});

Then we just pull any applicable rules:

Array.from(document.styleSheets).forEach((outerStyleSheet) => {
  Array.from(outerStyleSheet.cssRules).forEach((cssRule) => {
    // ...

    Array.from(this.classList).forEach((cssClass) => {
      console.log(cssClass);
      if (cssRule.selectorText.includes(`.${cssClass}`)) {
        styleSheet.sheet.insertRule(cssRule.cssText);
      }
    });
  });
});

Again, this means when developers/designers put in a CSS rule like below, the same specificity applies:

.groovy.funky {
  background-color: #ffccff;
}

Further work to do

So, as a proof of concept, this certainly works. I don't think it's a done job though, and I'm sure there'll be edge cases on the way.

For example, more complex selectors like #some-form dropdown-selector .option won't necessarily work with the current solution.

There's also the matter of media selectors and the new layer feature coming into CSS. I need to be able to pick out rules like this and appropriately apply them:

@media (prefers-color-sceme: dark) {
  dropdown-selector {
    background-color: #003300;
  }
}

I also use a lot of Tailwind CSS in my projects - but so far I've limited myself to using vanilla CSS. So, I'll need to come up with a solution that works well with Tailwind CSS. There's also a lot of other CSS frameworks, not to mention CSS-in-JS and so on.

One more thing: having this code pull in the styles every time the Web Component is used in a document is inefficient, so it looks like I'm going to have to get working on some kind of core enabling code to handle this.

The journey continues...

Using named grid lines to control layout

Stuart Jones — Wed, 16 Mar 2022 06:13:36 +0000

The ability to label the lines in a CSS Grid is an underused superpower, as far as I can tell. I've used it on several responsive layouts to easily move elements around a page as screen sizes vary.

For example, I was throwing a layout together last week and wanted it to look like this (padding and margins excluded):

There's a few ways to achieve this, but I also had to keep in mind how this would need to adapt to narrower/smaller screens. Particularly, the logo should shrink and some of the header area needed to move a little.

This is what I wanted the narrower design to look like:

Would you believe that there's only two lines of CSS that are different for these two layouts?

.container {
  display: grid;
  grid-template-columns: [left] auto 2rem [gutter-left logo-left] 6rem [logo-right title-left tagline-left] minmax(0, min-content) [gutter-right tagline-right title-right] 2rem auto [right];
  grid-template-rows: [top] 2rem [logo-top title-top] minmax(0, min-content) [header-bottom title-bottom tagline-top] minmax(0, min-content) [logo-bottom] minmax(0, min-content) [tagline-bottom main-top] 1fr [main-bottom footer-top] minmax(3rem, min-content) [bottom];
}

@media (max-width: 768px) {
  .container {
    grid-template-columns: [left gutter-left tagline-left] 1rem [logo-left] 2rem [logo-right title-left] 1fr [gutter-right tagline-right title-right right];
    grid-template-rows: [top title-top] 1rem [logo-top ] minmax(0, max-content) [header-bottom title-bottom tagline-top] minmax(0, max-content) [logo-bottom] minmax(0, max-content) [tagline-bottom main-top] 1fr [main-bottom footer-top] minmax(0, max-content) [bottom];
  }
}

How does it work?

When we define a grid, it may look like we're defining the widths and heights of the columns and rows:

.container {
  display: grid;
  grid-template-columns: minmax(0, max-content) 10rem 10rem auto;
  grid-template-rows: max-content 1fr max-content;
  min-height: 100%;
}

But what we're really doing is specifying the spacing between some grid lines. These lines are simply numbered, with the first line starting at 1.

We can refer to these line numbers when positioning elements inside our container:

header {
  grid-column: 1 / 5; /* take up the full width of the container */
}

main {
  grid-column: 2 / 4; /* occupy the centre */
}

footer {
  grid-column: 3 / 5; /* only take up the right half of the container */
}

Using numbered lines brings some extra maintenance - if we add or remove a column or row, we would have to change the relevant properties for child elements in the grid.

Instead, we could use names:

.container {
  display: grid;
  grid-template-columns: [left] 5rem [content-left] 1fr [center] 1fr [content-right] 5rem [right];
  grid-template-rows: max-content 1fr max-content;
  min-height: 100%;
}

header {
  grid-column: left / right; /* take up the full width of the container */
}

main {
  grid-column: content-left / content-right; /* occupy the centre */
}

footer {
  grid-column: center / right; /* only take up the right half of the container */
}

Now can easily rearrange things if we want to:

@media (max-width: 768px) {
  .container {
    grid-template-columns: [left content-left center] 100% [content-right right];
  }
}

This is a very simple example, which might be better solved by changing the containers display property to block - all children will then just be displayed as blocks in normal flow.

On the other hand, keeping it as a grid lets you use properties like gap to space child elements, and other grid related design.

However, I advise using clearer descriptive labels such as footer-left rather than center - especially as lines may move.

Overlapping elements

Ordinarily, I use grid-template-areas and grid-area to place elements in a layout, but there is one advantage that using grid start/end and lines have: you can easily overlap elements.

<style>
.container {
    display: grid;
    grid-template-columns: repeat(7, 1fr);
    grid-template-rows: repeat(7, 1em);
}
</style>

<div class="container">
    <div style="background-color: #000000; grid-column: 1 / 3; grid-row: 1 / 3;"></div>
    <div style="background-color: #003300; grid-column: 2 / 4; grid-row: 2 / 4;"></div>
    <div style="background-color: #006600; grid-column: 3 / 5; grid-row: 3 / 5;"></div>
    <div style="background-color: #009900; grid-column: 4 / 6; grid-row: 4 / 6;"></div>
    <div style="background-color: #00cc00; grid-column: 5 / 7; grid-row: 5 / 7;"></div>
    <div style="background-color: #00ff00; grid-column: 6 / 8; grid-row: 6 / 8;"></div>
</div>

<style>
.container {
    display: grid;
    grid-template-columns: repeat(5, 1fr);
    grid-template-rows: repeat(7, 1em);
    margin: 1rem auto;
}
</style>

<div class="container">
    <div style="background-color: #000000; grid-column: 1 / 3; grid-row: 1 / 8;"></div>
    <div style="background-color: #003300; grid-column: 2 / 4; grid-row: 2 / 7;"></div>
    <div style="background-color: #006600; grid-column: 3 / 5; grid-row: 3 / 6;"></div>
    <div style="background-color: #009900; grid-column: 4 / 6; grid-row: 4 / 5;"></div>
</div>

Things can get a bit tricky when we're trying to overlap content that we want to be able to fit content, alongside fixed height and width elements.

.container {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    grid-template-rows: 2rem auto auto 2rem;
    margin: 1rem auto;
    color: white;
}

When we don't overlap the blue and red elements, the rows marked auto behave as expected by being just the right size to fit the content from the red and blue elements.

However, if we place the red element as below, the middle rows each become half the height of the red element, which means the blue element stretches downwards.

If we stretch the red element across the bottom three rows, the middle two rows become half the height of the red element minus the 2rems we specified for the bottom row.

We can overcome this using minmax on the middle rows:

.container {
    display: grid;
    grid-template-columns: repeat(5, 1fr);
    grid-template-rows: 2rem minmax(0, max-content) minmax(0, 1fr) 2rem;
    margin: 1rem auto;
    color: white;
}

Back to the original example

I'll format the CSS to try and help:

.container {
  display: grid;
  grid-template-columns: [left] auto 
                         2rem 
                         [gutter-left logo-left] 8rem 
                         [logo-right title-left tagline-left] minmax(0, min-content) 
                         [gutter-right tagline-right title-right] 2rem 
                         auto
                         [right];
  grid-template-rows: [top] 2rem 
                      [logo-top title-top] minmax(0, min-content)
                      [header-bottom title-bottom tagline-top] minmax(0, min-content)
                      [logo-bottom] minmax(0, min-content)
                      [tagline-bottom main-top] 1fr
                      [main-bottom footer-top] minmax(3rem, min-content)
                      [bottom];
}

The two outer columns are both set to auto - basically centring the rest of the grid. The next two columns in on the left and right are fixed width. This allows us to stretch the header and footer backgrounds all the way across the screen, and ensure a minimum margin around the logo, title and other content.

We then have a fixed-width column to hold the logo, and then one other column that adapts to the width of the content, which lets us easily place the site name and tagline.

We set the width of the main content to 50ch (normally, I'd go with 80ch for readability) - but the main content is stretched across the fixed and flexible column. This means the flexible column ends up being 50ch - 6rem - and the title and tagline elements are kept within that width.

Similarly, the top row is fixed to put some space above the logo and title. Then we have some flexible rows that fit the title, and then the logo and tagline before we fill the page with the content and then the fixed height footer.

By setting the height of the logo, we 'fix' the height of two rows it sits in, while the overlapping header background will move up/down to fit the title, and the overlapping tagline pushes the main content down to make room for itself.

And when the title and tagline are shortened, our content still starts comfortably below the logo:

Limits

This is pretty complicated, and there a probably other ways to do this. But I like the idea of simply rearranging my grid and have its contents move accordingly.

There's also one odd issue that I uncovered as I put this blog post together - I can't account for the vertical space between the logo and the main content. If I put a background color on the tagline, we can see that the tagline is stretching a bit.

The discrepancy starts at 10 pixel, but as more text is added to the tagline and it wraps, it eventually reaches a point where the grid line for the logo bottom begins to move. From this point, the logo bottom line is exactly halfway between the title bottom and the tagline bottom.

We also see that there's no vertical space between the tagline and the content, so I would need some padding at the top of the content to make sure.

I was able to deal with this in the simpler overlapping examples earlier, but I haven't been able to solve this for the more complex layout. On the other hand, perfection is the enemy of done, and I got my layout working and adapting to screen sizes.

Making Web Components accessible

Stuart Jones — Thu, 17 Feb 2022 00:23:10 +0000

Last week, I set out to make a stylable and accessible replacement for the default <select> element. This started out from me building a custom date-picker for an app, and I wanted to create a standard that I could reuse.

I've lost count of the number of times I've created custom designed dropdowns over the years - and I'm also pretty sure that most of them fell short on accessibility, I'm sorry to say.

Stylable (or at least stylish) select boxes or dropdowns, or anything that seeks to replace the default and obstinate form elements, are also ten-a-penny. It also seems that most of them are bad at accessibility, too.

So why do this all over again? I think it is possible to get the accessibility right, without overcomplicating how the component is used in code. Another motivation is that I wanted to finally have a go at a pure vanilla web component - all my work with components so far has been within the Vue framework.

Resources

Before getting too far in, I did the reading. There's quite a few places which provide good background and examples for web components:

For the accessibility side of things, particularly with a select/dropdown component, these were my starting points:

I'll bring up other references as they become relevant.

Build-tools

Since this is vanilla JavaScript, you don't actually need any build tools - you could just write a html document and load it in the browser and the code we'll write below will work.

However, to make life a little easier I used the Web Dev Server from Modern Web which can watch for file changes and automatically refresh the browser.

Design

There were three main requirements I wanted to fulfil with this component:

Make it stylable
Make it accessible
Provide a good development experience (DX)

The first two are self-explanatory, but what do I mean by a good development experience?

Consider how <select> elements are written:

<form>
    <label for="manufacturer">Choose a manufacturer</label>
    <select id="manufacturer">
        <option selected>Ford</option>
        <option>Holden</option>
    </select>
</form>

I wanted people using my component to be able to follow the same pattern.

<form>
    <label for="manufacturer">Choose a manufacturer</label>
    <dropdown id="manufacturer">
        <option selected>Ford</option>
        <option>Holden</option>
    </dropdown>
</form>

First hurdle: web components must be hyphenated

I started simple:

<script>
    class Dropdown extends HTMLElement {
        constructor() {
            super();

            this.attachShadow({ mode: 'open' });
        }
    }

    customElements.define('dropdown', Dropdown);
</script>

<form>
    <label for="manufacturer">Choose a manufacturer</label>
    <dropdown id="manufacturer">
        <option selected>Ford</option>
        <option>Holden</option>
    </dropdown>
</form>

Result:

Failed to execute 'define' on 'CustomElementRegistry': "dropdown" is not a valid custom element name

I'd forgotten that custom elements names require a dash. This makes sense - it differentiates custom elements from standard ones, and prevents collision with potential future elements. There are a couple more restrictions and caveats, but dropdown-selector would be a reasonable name.

I also renamed the class to DropdownSelector - this isn't strictly necessary, but it makes it easy to match with the element.

After renaming the element, we can load the document and see that our options are missing. This is because the browser has swapped the contents of <dropdown-selector> with the contents of our custom element's Shadow DOM. Since the Shadow DOM is empty, nothing gets rendered here.

Creating a template for our accessible template to be styled

In order to be able to style the select and options, we can do something like this:

<div class="select">
    <div class="option"></div>
</div>

However, this immediately removes all semantic meaning for the user, and also loses the inherent behaviour that browsers afford <select> elements. So we'll have to provide the necessary meaning and behaviour this within our component. Luckily, the ARIA Authoring Practices provide an example dropdown pattern.

If we were to do this without a component, we would do something like this in our form:

<label id="manufacturer-label">Choose a manufacturer</label>
<div class="select">
    <div id="manufacturer-combo"
         class="combo"
         role="combobox"
         tabindex="0"
         aria-controls="manufacturer-list"
         aria-expanded="false"
         aria-haspopup="listbox"
         aria-labelledby="manufacturer-label"
    />
    <div id="manufacturer-list"
         class="options"
         role="listbox"
         tabindex="-1"
         aria-labelledby="manufacturer-label"
    >
        <div class="option" id="manufacturer-option-0">Ford</div>
        <div class="option" id="manufacturer-option-1">Holden</div>
    </div>
</div>

To get started on a component-based solution, we'll replace the content of the page's body with this:

<script>
  class DropdownSelector extends HTMLElement {
    constructor() {
      super();

      this.attachShadow({ mode: 'open' });

      this.shadowRoot.innerHTML = html;
    }
  }

  const html = `<div class="select">
    <div class="combo"
         role="combobox"
         tabindex="0"
         aria-controls="options"
         aria-expanded="false"
         aria-haspopup="listbox"
         aria-labelledby="label"
    ><!-- show the current selected value here --></div>
    <div id="options"
         class="options"
         role="listbox"
         tabindex="-1"
         aria-labelledby="label"
    ><!-- list of options here --></div>
</div>

<!-- styles defined here will not leak out of the component -->
<style>
    * {
        box-sizing: border-box;
    }

    .select { 
        height: 3em;
        width: fit-content;
    }

    .combo {
        outline: 3px solid #999999;
        border-radius: 0.25em;
        padding: 1em;
    }
</style>`;

  customElements.define('dropdown-selector', DropdownSelector);
</script>

<form>
    <label for="manufacturer">Choose a manufacturer</label>
    <dropdown-selector id="manufacturer">
        <option selected>Ford</option>
        <option>Holden</option>
    </dropdown-selector>
</form>

Now we should be seeing something like this:

We need to address the label

The label is a problem. It's sitting outside of our component, because we're trying to maintain the usual label/select pattern with our custom element. However, there's a fairly clear delineation between the Shadow DOM inside our component and the main document outside. This means that there's no relationship between that label and the component.

For mouse users, if you click on the label - nothing happens. Even worse, if you are using a screenreader and use the tab key to set the dropdown as the active element, the label is not read out and even announce the function of the dropdown incorrectly, creating obvious confusion.

I resolved this problem by having my component look for a label and pull it in:

class DropdownSelector extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: 'open' });

    this.shadowRoot.innerHTML = html;

    this.__parentLabel = document.getElementById(this.getAttribute('aria-labelledby'));
    this.__label = this.shadowRoot.getElementById('label');

    this.__label.innerHTML = this.__parentLabel.innerHTML;
  }
}

This solution does mean we can't use the for attribute on original label, so we need to change our HTML a little:

<label id="manufacturers-label">Choose a manufacturer</label>
<dropdown-selector aria-labelledby="manufacturers-label">
    ...
</dropdown-selector>

Unfortunately, this will produce an error, but this can be resolved by specifying our script as a module:

<script type="module">
    ...
</script>

This allows our class to access the attributes on the original dropdown-selector and pull in the label.

I wish I knew why this is the case - simply setting the script to defer (which is implicit in using the module type) doesn't seem to work. However, the type="module" attribute is required when it comes time to extract the code into an external script that can be imported by the browser.

Now that we have this working, we should be seeing double labels:

We don't want to force developers to create special rules for the labels they're associating with our component. However, our label needs to be 'visible' to allow screenreaders to associate it with the combobox and listbox elements in our component, so we can't simply use display: hidden. So, in our component styles we can just fling it off to the side somewhere:

    label {
        position: absolute;
        left: -1000px;
    }

Developers using our component can now consistently style the original label to match their other labels. Screenreaders will ignore the original label, since it doesn't relate to anything - and they will use the one we have inside our component to correctly announce the label and component's function when focus is given.

However, we have one more thing to do - since there is still no functional relationship between the original label and our component, clicking on the label won't activate the component like we expect with other label/input pairings.

We can compensate for this from within our component:

class DropdownSelector extends HTMLElement {
  constructor() {
  ...
  }

  connectedCallback() {
    if (this.isConnected) {
      if (this.__parentLabel) {
        this.__label.textContent = this.__parentLabel.textContent;

        this.__parentLabel.addEventListener('click', this.click.bind(this));
      }
    }
  }

  disconnectedCallback() {
    if (this.__parentLabel) {
      this.__parentLabel.removeEventListener('click', this.click.bind(this));
    }
  }

  click(event) {
    this.shadowRoot.getElementById('combo').focus();
  }
}

And if we add a little style to the combobox, we can see it happening:

    .combo:focus {
        outline: 3px solid #99ccff;
        border-radius: 0.25em;
        padding: 1em;
    }

It's good to have options

Now that users can access our component, we need to provide them the options. We need to consider the following standard behaviour for <option> elements:

they have an optional value attribute. If this is unset, the option's value is based on it's text content;
and they have an optional selected attribute. In a dropdown context, there should only be one such element.

First, we need to get the list of options defined in the original HTML, and then render the options within our component.

class DropdownSelector extends HTMLElement {
  constructor() {
    super();

  ...

    this.__listbox =

      this.options = [...this.querySelectorAll('option')].map((option, index) => {
        return {
          label: option.textContent,
          selected: option.hasAttribute('selected'),
          value: option.getAttribute('value') ?? option.textContent,
        }
      });
  }
}

We'll now see our options listed. We could hide them until the dropdown has focus, using display: hidden. However, a feature of <select> inputs is that they default to a width that fits its content. If we simply hide the options, then our dropdown will default to fit the content that remains visible (that is, the selected option), but will resize to fit the longest available option when opened.

To avoid this, we'll just use some overflow magic:

    .options {
        height: 0;
        overflow-y: hidden;
        position: relative;
        background-color: #fafafa;
    }

    .combo[aria-expanded=true] ~ .options {
        height: auto;
        outline: 3px solid #999999;
        border-radius: 0.25em;
    }

Even though the content is technically visible, screenreaders won't see the content in the list until we inform them that the list is expanded by updating the relevant aria attributes. To make our dropdown behave more like a standard select element, we need to manage the open/close status of the list:

  constructor()
  {
    ...

    this.__combobox = this.shadowRoot.getElementById('combo');
  }

  connectedCallback() {
    if (this.isConnected) {
      ...

      this.__combobox.addEventListener('blur', this.blur.bind(this));
      this.__combobox.addEventListener('click', this.click.bind(this));
    }
  }

  disconnectedCallback() {
    ...

    this.__combobox.removeEventListener('blur', this.blur.bind(this));
    this.__combobox.removeEventListener('click', this.click.bind(this));
  }

  blur(event) {
    this.closeList();
  }

  click(event) {
    this.open ? this.closeList() : this.openList();
  }

  closeList() {
    this.open = false;
    this.__combobox.setAttribute('aria-expanded', 'false');
    this.__combobox.setAttribute('aria-activedescendant', '');

    this.__combobox.focus();
  }

  openList() {
    this.open = true;
    this.__combobox.setAttribute('aria-expanded', 'true');

    this.currentIndex = this.selectedIndex;

    this.__combobox.setAttribute('aria-activedescendant', `option-${this.currentIndex}`);

    const options = this.__listbox.querySelectorAll('[role=option]');
    [...options].forEach((option) => {
      option.classList.remove('current');
    });
    options[this.currentIndex].classList.add('current');

    this.__combobox.focus();
  }
}

Now we've added the list, we can provide a little bit more styling:

  .option {
    padding: 1em;
  }

  .option.current {
    outline: 2px solid #acdcfc;
    background-color: #f0f0f0;
  }

  .option:hover {
    background-color: #acdcfc;
  }

When we click on the combo box, we should now see the styled list of options:

Setting the value

Initial selection

By default, when a <select> is displayed it shows the text for whichever <option> element has a selected attributed. If none of the options have been selected, the <select> shows the text for the first option.

  constructor() {
    ...

    if (this.selectedIndex === null) {
      this.selectedIndex = 0;
    }

    if (this.options[0]) {
      this.__combobox.textContent = this.options[this.selectedIndex].label
      this.value = this.options[this.selectedIndex].value;
    }
  }

When a user selects an option

We need to update the selection whenever a user selects an option. However, if the user is clicking with a mouse, the browser will also detect a mousedown event, which causes the combobox to lose focus and trigger the blur event handler we wrote which closes the list, and this will interfere with the selection.

To get around this, we'll use a flag which allows us to ignore the blur event when we need to:

  connectedCallback() {
    [...this.__listbox.children].forEach((element, index) => {
      element.addEventListener('click', (event) => {
        event.stopPropagation();
        this.select(index);
        this.click(event);
      });
      element.addEventListener('mousedown', this.setIgnoreBlur.bind(this));
    });
  }

  blur(event) {
    if (this.ignoreBlur) {
      this.ignoreBlur = false;
      return;
    }

    this.closeList();
  }

  select(index) {
    this.currentIndex = index;
    this.selectedIndex = index;

    this.value = this.options[index].value;
    this.__combobox.textContent = this.options[index].label;

    const options = this.__listbox.querySelectorAll('[role=option]');
    [...options].forEach((option) => {
      option.setAttribute('aria-selected', 'false');
    });
    options[index].setAttribute('aria-selected', 'true');
  }

Keyboard events

Without reacting to keyboard events, we don't have a fully accessible component.

The ARIA ComboBox Example is a great resource for how the component should react to various keyboard events.

We need to listen for a keydown event, and then determine what action to take:

const Actions = {
  Open: 0,
  Close: 1,
  Up: 2,
  Down: 3,
  PageUp: 4,
  PageDown: 5,
  First: 7,
  Last: 8,
  Select: 9,
  SelectAndClose: 10,
};

class DropdownSelector extends HTMLElement {
  connectedCallback() {
    ...

    this.__combobox.addEventListener('keydown', this.keydown.bind(this));
  }

  ...

  keydown(event) {
    const action = this.actionFromKey(event);

    switch (action) {
      case Actions.First:
      case Actions.Last:
        this.openList();
      // intentional fallthrough
      case Actions.Up:
      case Actions.Down:
      case Actions.PageUp:
      case Actions.PageDown:
        event.preventDefault();
        this.updateCurrentIndex(action);
        this.refreshList();
        break;
      case Actions.SelectAndClose:
        event.preventDefault();
        this.select(this.currentIndex);
      // intentional fallthrough
      case Actions.Close:
        event.preventDefault();
        this.closeList();
        return;
      case Actions.Open:
        event.preventDefault();
        this.openList();
        return;
    }
  }

  actionFromKey(event) {
    const {key, altKey, ctrlKey, metaKey} = event;
    const openKeys = ['ArrowDown', 'ArrowUp', 'Enter', ' ']; // all keys that will do the default open action
    // handle opening when closed
    if (!this.open && openKeys.includes(key)) {
      return Actions.Open;
    }

    // home and end move the selected option when open or closed
    if (key === 'Home') {
      return Actions.First;
    }
    if (key === 'End') {
      return Actions.Last;
    }

    if (this.open) {
      if (key === 'ArrowUp' && altKey) {
        return Actions.SelectAndClose;
      } else if (key === 'ArrowDown' && !altKey) {
        return Actions.Down;
      } else if (key === 'ArrowUp') {
        return Actions.Up;
      } else if (key === 'PageUp') {
        return Actions.PageUp;
      } else if (key === 'PageDown') {
        return Actions.PageDown;
      } else if (key === 'Escape') {
        return Actions.Close;
      } else  if (key === 'Enter' || key === ' ') {
        return Actions.SelectAndClose;
      }
    }
  }

  updateCurrentIndex(action) {
    const max = this.options.length - 1;

    switch (action) {
      case Actions.Up:
        this.currentIndex -= 1;
        break;
      case Actions.Down:
        this.currentIndex += 1;
        break;
      case Actions.PageUp:
        this.currentIndex -= 10;
        break;
      case Actions.PageDown:
        this.currentIndex += 10;
        break;
      case Actions.First:
        this.currentIndex = 0;
        break;
      case Actions.Last:
        this.currentIndex = max;
        break;
    }

    if (this.currentIndex > max) {
      this.currentIndex = max;
    }
    if (this.currentIndex < 0) {
      this.currentIndex = 0;
    }
  }

  refreshList() {
    this.__combobox.setAttribute('aria-activedescendant', `option-${this.currentIndex}`);

    const options = this.__listbox.querySelectorAll('[role=option]');
    [...options].forEach((option) => {
      option.classList.remove('current');
    });
    options[this.currentIndex].classList.add('current');
  }
}

And we're done

So that's an accessible web component for providing a dropdown-style select. This is the starting point for a library of accessible web components - the code is out on GitHub.

However, there is a bit more work before the package will be published onto npm:

What about stylablility?

Unfortunately, controlling the style of web components is almost as hard as controlling the style of native select and option elements. Almost.

CSS Tricks have written about this over the years, keeping up with changes in stylability, and also bringing new approaches as they come about.

In some ways, it's good that there is a separation between the style within web components and the document outside - you don't want leaky styles from a component messing up your design. On the other hand, it would be nice to provide some more control for developers using components. That certainly feels like what was promised in the first discussions around web components. We also see this ability when using Vue or other frameworks (although they may approach components slightly differently).

However, since we can pass some information between document and shadow DOMs, there is some ability to pass document styles into the shadow. I'll be writing about that soon.

What about reactivity?

What if the developer wants to provide or select options programmatically?

I don't know, yet... I have a couple of experiments to try out and will write it up when I have something workable.

More components?

I don't plan on just this one component - I need a variety of accessible components for my own projects, so plan on building a library of them as I go along. I'm also hoping that this will help and encourage others to use more accessible solutions in their own work.

Framework support?

This component is pure vanilla ES6 - which makes it really easy to use alone in modern browsers. I am aware that a lot of frontend work is built using frameworks/libraries like Vue or React, and will undertake some testing and any necessary improvements to make it as easy as possible to use these components in the popular frameworks.

CSS Grid Golf

Stuart Jones — Mon, 22 Nov 2021 03:52:41 +0000

I've been playing with CSS Grid quite a bit - trying to see exactly what it can and can't do. One thing I decided to have a go at is what minimum amount of code is required to create a valid grid layout.

A simple two column layout

.container {
  display: grid;
  grid: '. .';
}

This CSS rule will create a grid containing two columns. If the container has more than two child elements, then it will automatically generate new rows as required:

<div class="container">
    <div>This is the first element.</div>

    <div>Here we have another element.</div>

    <div>This element should now be shown on the next row.</div>
</div>

As you can see in the above example, the columns may adjust to fit the content as best they can. If you want more control of the column widths, you can define them in the same grid property. For example, if you want the two columns to always be equal, regardless of content, you can set the first column to be 50%. The second column will the fill the other 50% and no more:

.container {
  display: grid;
  grid: '. .' / 50%;
}

You can specify the width of the first column as a percentage or a fixed value, and the second column will automatically take up the extra space:

.container {
  display: grid;
  grid: '. .' / 200px;
}

Alternatively, you can specify both the column widths explicitly:

.container {
  display: grid;
  grid: '. .' / 200px 50%;
}

Three columns (or more)

You can define as many columns as you like. If you don't specify any column widths, then they will default to being equal, but with the ability to grow depending on content:

.container {
  display: grid;
  grid: '. . .';
}

If you set a width for the first column, then the remaining two columns will divide the remaining space between themselves:

.container {
  display: grid;
  grid: '. . .' / 50px;
}

You can set the column width for any number of columns from left to right, with the remaining columns sharing the remaining space:

.container {
  display: grid;
  grid: '. . . . .' / 25px 75px 25px;
}

Controlling grid rows

This is where things start to get messy. The grid property is a shorthand for several other properties. So far we've used the property to specify grid-template-areas and grid-template-columns in the examples above.

Using the grid rule, we can also take control of the height of grid rows. Take this single column - the first row will

.container {
  display: grid;
  grid: '.' 10rem;
}

To control the heights of multiple rows:

.container {
  display: grid;
  grid: '.' 10rem
        '.' 5rem;
}

Rows and columns

.container {
  display: grid;
  grid: '. .' 5rem
        '. .' 5rem;
}

Every row must have the same number of columns:

.container {
  display: grid;
  grid: '. .' 5rem
        '. . .' 5rem;
}

If you want to control column widths:

.container {
  display: grid;
  grid: '. .' 5rem
        '. .' 
        / 200px;
}

See what I mean about getting a bit messy - and we've only done about half the things that the grid property itself can use.

Be explicit

While the grid shorthand is nice for fairly trivial layouts, it is a fairly powerful shorthand, which means it can quickly get quite complex when trying to add in lots of rules. In fact, we've only covered about half of the properties that grid can handle.

While coding golf experiments can be fun and instructive, I prefer to be more explicit/expressive with actual code. Anything beyond the simple column definitions like above, and I would rather avoid using the shorthand property.

.container {
  display: grid;
  grid-template-areas: '. .'
                       '. .';
  grid-template-columns: 200px 1fr;
  grid-template-rows: 5rem 
                      min-content;
}

Money - and how to handle it

Stuart Jones — Wed, 11 Aug 2021 05:57:53 +0000

Many years ago, one of my first tasks as a developer was to make some changes to an application that my company's salesmen used to estimate the price for customer projects.

After I started digging around, the second thing I noticed (after seeing all the comments were in German) was that the prices of everything (hardware, software, engineering time) were stored as integers and were divided by 10,000 when presented to show the price in £ (British pounds).

I asked my boss about this, and I was told that "this was how sales and accounting software deals with money".

After learning this, I quickly worked out why.

Why not float (or double, or real)?

Almost all modern computers store data as binary information, and perform binary mathematics. This is fine for whole numbers (up to a limit), since any number can be represented as a combination of various powers of 2. For example, the value 23 is stored in 8-bit memory as 00010111, which is 16 + 4 + 2 + 1 or 2^4 + 2^2 + 2^1 + 2^0.

This would be great if all numbers are whole numbers. However, we needed to be able to perform mathematics and handle numbers that have fractional components - such as, 0.1, 1/3, sin(45°), or the square root of 2. There were a few different approaches to this problem, but since the 1980s almost every computer and programming language uses the same solution - the IEEE 754 standard - and this is the basis for the float and double types used in various programming languages, also known as floating-point types.

Floating-point types are not perfect, the limitations of binary storage creates some minor issues, but for most applications they are good enough.

Consider this, though:

echo 0.1 + 0.2; // 0.3
echo (0.1 + 0.2) === 0.3; // nothing

console.log(0.1 + 0.2); // 0.30000000000000004

These seem a little harmless, and could be fixed by using rounding functions, although this can be a little cumbersome:

echo round(0.1 + 0.2, 1) === 0.3; // 1

console.log(Math.round(10*(0.1 + 0.2))/10); // 0.3

There can also be problems with rounding some numbers:

echo round(0.4999999999999999); // 0
echo round(0.49999999999999999); // 1

echo 0.4999999999999999; // 0.5
echo 0.49999999999999999; // 0.5

console.log(Math.round(0.4999999999999999)); // 0
console.log(Math.round(0.49999999999999999)); // 1

These discrepancies may seem small, but do enough financial mathematics - add and subtract values, perform discounts and apply tax calculations - and eventually you'll get tripped up, and receive a call or email from your head of finance or clients or customers (or maybe all three).

Fixed-point types

Some languages, including SQL, have a fixed-point type. These allow for decimal values that are store with the same precision as integers.

Unfortunately, if you are using standard PHP or JavaScript (the Number.toFixed() method is for presentation and outputs a string), these fixed-point types will be cast to floating-point types, and end up with the same precision errors you are trying to avoid.

They also have limitations in that you have to specify the size and precision of the fixed-point numbers you want to use. For example, in MySQL, setting a column to DECIMAL(5,2) will let you store values from -999.99 to 999.99, but you will encounter errors if you try to set the field to 10,000 or 0.001. This means that you need to be aware of the range and precision you need before using it.

There is a PECL package that provides Decimal support to PHP, and also a library for JavaScript.

Money as an integer

So, to avoid all these floating-point precision issues, you should store and work with money values as integers.

There's a couple of ways to do this, such as having a dollars and cents column (or pounds/pence or whatever). However, the simplest approach is to have a single column/value and use a precision factor to convert the number as a money value for presentation.

Depending on how you're accessing the database you can cast the value into a simple Money object, which handles the presentation and so on. You could even wrap or extend this with Currency object that would handle currency symbols and localised formatting (sometimes the currency symbol precedes the value, sometimes it comes after - some countries write numbers like 1,234.56, some 1 234.56, and others 1.234,56).

Convert SVG images in the browser using JavaScript and the Canvas API

Stuart Jones — Tue, 01 Sep 2020 13:53:03 +0000

SVG (Scalable Vector Graphics) have a few advantages over the usual image formats we use on websites. Firstly, it is possible to style them using CSS, making them very flexible. For some applications, they can also be smaller in filesize than the equivalent high quality PNG or JPEG. They can also be animated. Finally, just as it says in the name, they are scalable. This means they can be enlarged or shrunk down without pixelation or other shenanigans that you would get with a PNG or JPEG image - although photographs and other high-detail images are not suitable for SVG.

SVG (top) and PNG (bottom) images at 50 (left) and 100 (right) pixels.

However, I found myself at the limit of the usefulness of SVG recently (although, that's not SVGs fault).

The problem

I've been putting together a Game of Life board together as one of my experiments, and wanted to replace the solid black squares I was using with something with little more texture to it.

Comparing the old black tile on the left with a new "textured" tile on the right, at different sizes.

The game uses a <canvas> element, which can be manipulated with the Canvas API, and the original code for drawing a cell looked this (the project is built in Vue.js and the source is available on GitHub):

drawCell(x, y, state) {
    let context = this.$refs.canvas.getContext('2d');

    switch (state) {
        case DEAD:
            context.fillStyle = 'white';
            break;

        case ALIVE:
            context.fillStyle = 'black';
            break;
    }

    // fill the grid square but leave the grid outline
    context.fillRect(
        (x * this.cellSize) + 1,
        (y * this.cellSize) + 1,
        this.cellSize - 2,
        this.cellSize - 2
    );
}

Cloning images

As a first pass, I replaced that method with this much shorter one:

drawCell(x, y, state) {
    let context = this.$refs.canvas.getContext('2d');

    context.drawImage(this.images[state], (x * this.cellSize), (y * this.cellSize), this.cellSize, this.cellSize);
}

drawImage(Image, x, y, height, width) accepts any previously loaded image data - including PNG, JPEG, and SVG.

Unfortunately, because the cell size can be controlled by the user, any PNG image I used would be subjected to the usual problems that come from resizing images, so I went ahead with using SVG.

I used the component's mounted method to preload the two images:

async mounted() {
    this.images = {
        'alive': await loadImage("./img/alive.svg"),
        'dead': await loadImage("./img/dead.svg"),
    }

    this.initialiseMap();
}

loadImage is a simple function which allows the images to be loaded asynchronously, and so ensures that the images are available before the component tries to render them.

function loadImage(url, height, width) {
    return new Promise((resolve, reject) => {
        let image = new Image();

        image.onload = () => {
            resolve(image);
        }
        image.onerror = reject;

        image.src = url;
    });
}

Ground to a halt

Unfortunately, this implementation caused the whole drawing cycle to grind down drastically, and was taking tens of seconds to redraw each generation. This was quite the setback, considering the old filled square method was lightning fast, even on quite large boards.

I had hoped to fend off the worst performance issues by preloading the SVGs - but it seems the resizing and drawing for each cell was still a pretty expensive operation.

Was I doomed to have flat black tiles? I had one more thing to try.

Converting SVG to PNG

Remember that drawImage can accept any loaded image data? This data doesn't have to come directly from a file. It's possible to extract image data from another canvas element and use that where any other image can be used, including drawImage.

I updated my loadImage function:

function loadImageAsPNG(url, height, width) {
    return new Promise((resolve, reject) => {
        let sourceImage = new Image();

        sourceImage.onload = () => {
            let png = new Image();
            let cnv = document.createElement('canvas'); // doesn't actually create an element until it's appended to a parent, 
                                                        // so will be discarded once this function has done it's job
            cnv.height = height;
            cnv.width = width;

            let ctx = cnv.getContext('2d');

            ctx.drawImage(sourceImage, 0, 0, height, width);
            png.src = cnv.toDataURL(); // defaults to image/png
            resolve(png);
        }
        image.onerror = reject;

        image.src = url;
    });
}

The toDataURL(type, encoderOptions) method here accepts a mime-type string (image/png, image/jpeg, etc), and return base-64 encoded image data that can be used as the source for another Image. If it doesn't support the requested mime-type, or if you don't provide one, it returns a PNG. The second parameter is used to control image quality for "lossy" types like JPEG. This takes a number between 0 and 1 - the default is 0.92.

Finally, toDataURL can also output the newer WebP type - but only in Chrome (which is okay because it will default to PNG in other browsers).

Final thoughts

This isn't ideal - drawImage is still a costly function, and larger boards are still quite slow, so I need to search for other optimisations.

However, if you ever need to convert from one image type to any other (supported) type in a browser, think about the Canvas API and its toDataURL method. The toDataURL can even be used to get the image data from a Canvas that has been drawn on by the user (if your app supports that) and send it up to a server to be saved as a file.

Drag and drop elements on touch devices

Stuart Jones — Mon, 17 Aug 2020 02:00:14 +0000

I've been playing around with dragging and dropping stuff in web browsers for a while. ViewCrafter relies on the Drag and Drop API, since it enables me to pass data easily to drop targets in different windows. I'll probably do a blog post about that at some point.

This blog post is about being able to move an element by dragging it around on a touch screen. Unfortunately, the Drag and Drop API isn't supported all that well on touch devices, and so I've had to dig a bit into the Touch API to provide an experience for the user that works on touch and on traditional desktop browsers.

If you want to see an application of this ability, take a look at my Tower of Hanoi game.

Building up a solution

To get this working, we need a simple layout:

<html>
    <div id="container">
        <div id="left-parent">
            <div id="movable-element"></div>
        </div>

        <div id="right-parent"></div>
    </div>
</html>

Okay, this is a bit bland (and empty), so we'll put in a bit of styling to get a visible layout.

* {
  box-sizing: border-box;
}
#container {
  display: flex;
}

#container > div {
  border: 1px solid gray;
  padding: 1em;

  height: 10em;
  width: 50%;
}

#movable-element {
  border: 1px solid green;
  background-color: #00ff0033;
  height: 100%;
  width: 100%;
}

Our objective is to enable the user to move the green element from the left parent to the right, and back again - while updating the document.

How to pick up and make a move

We want the same interaction for the user whether they're using a mouse or using a touch device. So, we're going to programme both functionalities in tandem. This is helped by the fact that there are analogous events between both APIs:

touchstart is equivalent to mousedown
touchend is equivalent to mouseup
touchmove is equivalent to mousemove

There's a couple of caveats. Touch has an additional touchcancel event which is triggered when the browsers decides something should interrupt the touch behaviour. Also, the touch events carry additional information because you can have multiple touchpoints, whereas the Mouse API only allows for a single mouse pointer.

All that consider, our first step is to allow users to 'pick up' the element. This is done by listening for mousedown and touchstart events on the movable element.

<div id="movable-element" onmousedown="pickup(event)" ontouchstart="pickup(event)"></div>

let moving = null;

function pickup(event) {
    moving = event.target;
}

Nothing much will happen yet, since we also need to track our mouse/finger movements and move the element to match.

To do this we need to change the element's position to fixed, and also listen out for changes in the mouse/finger position, using mousemove and touchmove.

<div id="movable-element"
     onmousedown="pickup(event)" 
     ontouchstart="pickup(event)" 
     onmousemove="move(event)" 
     ontouchmove="move(event)"
></div>

let moving = null;

function pickup(event) {
    moving = event.target;

    moving.style.position = 'fixed';
}

function move(event) {
    if (moving) {
        // track movement
    }
}

Now when we click on the element:

Oh dear - what just happened?

The moving element uses relative height to fill the space available in its parent. When we change its positioning to fixed, the element attempts to fill the whole page, hence the blowout. This is easily fixed, though:

function pickup(event) {
    moving = event.target;

    moving.style.height = moving.clientHeight;
    moving.style.width = moving.clientWidth;
    moving.style.position = 'fixed';
}

Let's get moving

The tricky bit here is that mousemove and touchmove pass slightly different information in the event. This is because touchmove allows for multiple touchpoints to move around the screen (a feature that would allow us to do things like pinch-zoom and rotate, if we so wished).

function move(event) {
    if (moving) {
        if (event.clientX) {
            // mousemove
            moving.style.left = event.clientX - moving.clientWidth/2;
            moving.style.top = event.clientY - moving.clientHeight/2;
        } else {
            // touchmove - assuming a single touchpoint
            moving.style.left = event.changedTouches[0].clientX - moving.clientWidth/2;
            moving.style.top = event.changedTouches[0].clientY - moving.clientHeight/2;
        }
    }
}

We use clientX and clientY here to account for the page being scrolled. The element is being positioned relative to the window's left and top edges, so we want to know where our mouse/finger is relative to the window's top-left corner.

Now we have our element tracking our mouse/finger movements, but there a couple more problems now:

The element sticks to the mouse pointer when we let go of the button.
The element just sits wherever we left it when we lift up our finger.

Let it go!

What we need to do now is react to the user letting go of the element (mouseup and touchend):

<div id="movable-element"
     onmousedown="pickup(event)"
     ontouchstart="pickup(event)"
     onmousemove="move(event)"
     ontouchmove="move(event)"
     onmouseup="drop(event)"
     ontouchend="drop(event)"
></div>

function drop(event) {
    if (moving) {
        // reset our element
        moving.style.left = '';
        moving.style.top = '';
        moving.style.height = '';
        moving.style.width = '';
        moving.style.position = '';

        moving = null;
    }
}

Drop it like it's hot

The final piece of the puzzle is getting the element to actually move when we drop it where we want it to go.

So, we need to know where we've dropped it.

The problem is, because we've made our element move everywhere underneath our pointer/finger, the event's target information is just going to give us the element we're moving, and not any information about where we're trying to drop it.

To overcome this, we can set the z-index of our element so that it appears behind the elements we're moving between. Unfortunately, this hides the element and prevents the event listeners for moving and releasing the element from firing, so we have to make a few changes to where we place them.

<html onmouseup="drop(event)" ontouchend="drop(event)">
    <div id="container" onmousemove="move(event)" ontouchmove="move(event)">
        <div id="left-parent" onmouseup="drop(event)" ontouchend="drop(event)">
            <div id="movable-element" onmousedown="pickup(event)" ontouchstart="pickup(event)"></div>
        </div>

        <div id="right-parent" onmouseup="drop(event)" ontouchend="drop(event)"></div>
    </div>
</html>

function pickup(event) {
    moving = event.target;

    moving.style.height = moving.clientHeight;
    moving.style.width = moving.clientWidth;
    moving.style.position = 'fixed';
    moving.style.zIndex = '-10';
}

function drop(event) {
    if (moving) {
        // reset our element
        moving.style.left = '';
        moving.style.top = '';
        moving.style.height = '';
        moving.style.width = '';
        moving.style.position = '';
        moving.style.zIndex = '';

        moving = null;
    }
}

Putting the move listeners on the container constrains the movement to within that part of the page (if you want to be able to move everywhere, you can put the listeners on the <html> element instead).

We put the mouseup and touchend listeners on the <html> element so that it doesn't matter where we let go of the mouse or lift up our finger, the element will return to its original location (unless a different element's event listener prevents that). Finally, we put a mouseup and touchend listener on each target area (including the original parent for when we want to move back).

Now we're ready to move our element from one part of the document to another.

function drop(event) {
    if (moving) {
        if (event.currentTarget.tagName !== 'HTML') {
            event.currentTarget.appendChild(moving);
        }

        // reset our element
        moving.style.left = '';
        moving.style.top = '';
        moving.style.height = '';
        moving.style.width = '';
        moving.style.position = '';
        moving.style.zIndex = '';

        moving = null;
    }
}

event.currentTarget tells us which element the event triggered on. appendChild moves the element from it's original parent to the new one. At least, it works on desktops. We have to do something else to get it to work on touch screens.

Touchy touch screens

For some reason, on touch devices, event.currentTarget gives us the parent of the element we're moving - not the parent we're trying to move to. I don't understand the variation in behaviour here, because touch and mouse have been pretty consistent so far.

Luckily, there is native javascript function that tells us what element is under a specific point on the page - elementFromPoint.

function drop(event) {
    if (moving) {
        if (event.currentTarget.tagName !== 'HTML') {
            let target = null;
            if (event.clientX) {
                target = document.elementFromPoint(event.clientX, event.clientY);
            } else {
                target = document.elementFromPoint(event.changedTouches[0].clientX, event.changedTouches[0].clientY);
            }

            target.appendChild(moving);
        }

        // reset our element
        moving.style.left = '';
        moving.style.top = '';
        moving.style.height = '';
        moving.style.width = '';
        moving.style.position = '';
        moving.style.zIndex = '';

        moving = null;
    }
}

That's all

So, there we go, we can now move an element from one parent to another by dragging it with a finger.

About the only problem with this solution is that setting a negative z-index on the moving element means it could get obscured by other elements that are not transparent as we move it around. There is an experimental extension to elementFromPoint - elementsFromPoint - but it hasn't been fully implemented by all browsers yet. There's also the issue of identifying which of the many elements under that point we want.

Renaming your master branch

Stuart Jones — Sun, 07 Jun 2020 04:09:39 +0000

While it is possible to rename your master branch just like any other branch, there's a few gotchas that you have to look out for.

Why change?

Language and words have a power and, unfortunately, some words and terminology we have historically used in technology (and in everyday conversation) are not neutral - they have an inadvertent and inherent ability to hurt some sections of our society. Here's an article from the Internet Engineering Task Force (IETF) on Terminology, Power and Oppressive Language.

What name?

Master is the default branch name when initialising a new git repository, and this is expected by many developers. While no branch in git is really special, many workflows rely on the master branch to maintain the thread of development - so any new name needs to convey that same sense of being the centre of the workflow.

I've seen people propose development (although, aren't all branches "development"?), trunk (a term from SVN, indicating this is what is branched from, but not necessarily intuitive), or release (which may not be the case for some repositories).

The name that seems to be most common for repositories that rename master is main. I also think it is neutral and reasonably obvious, so this is the name I decided to use.

Playing well with others

If you've got a reasonably popular public repository, you might find some people get caught out with the change - so it is probably a good idea to communicate to any collaborators that this change is coming.

Renaming locally

This is pretty easy to do:

git branch -m master newname

Done. If you do git branch you will see newname listed instead of master.

However, this will only work if there is at least one commit (because the master branch isn't actually created until that commit). You can make a simple commit (I usually create a .gitignore file as an initial commit), or you can do this:

git symbolic-ref HEAD refs/heads/newname

Change the value of the HEAD reference will have you start on the new default right from the start.

Renaming a remote master branch

(as a convention, I will use origin for the remote repository)

This is where I came a little unstuck - trying to rename a branch hosted on GitLab.

Renaming a remote branch from your local machine requires you to push to the new branch and then remove your old one:

git branch -m master newname
git push -u origin newname
git push origin :master

git push -u tells your local branch to start following the new remote. git push origin :master tells the remote repository to remove the master branch there.

However, I got an error like this from my private GitLab server:

! [remote rejected] master (pre-receive hook declined)
error: failed to push some refs to 'example.com.au:horuskol/horuskol.net.git'

This was because of GitLab managing the default branch and setting some protections on that branch to prevent accidental deletion.

Removing a master branch from GitLab

First, push the new default to GitLab git push -u origin newname.

In GitLab, open the project you want to remove the master branch from.

Click on the project Settings menu and then Repository.

Expand the Default Branch section and change the default branch from the available branches.

Expand the Protected Branches section and remove any protection on master, as well as set any protections you want on the new default branch.

Then you will be able to delete the old remote master with git push origin :master.

Removing a master branch from GitHub

First, push the new default to GitHub git push -u origin newname.

Then, in GitHub, open the repository and click on the branches link.

Click on the Change Default Branch button and then select the new default branch.

You will now be able to delete the old remote master with git push origin :master.

Other remotes

I don't have an account with any other git remote repository service (such as BitBucket), so can't provide instruction for those.

Can we change the default?

It would be great if we could override git's default behaviour when creating a new repository, because we could set this up without ever having to think about it again.

When I tried finding a solution, I hit a lot of commentary about how this is hard-coded into git and found some ugly scripting solutions. However, another member of the Adelaide HeapsGoodDev community, Leigh Brenecki, has a great write up on changing the default branch for new Git repositories.

PHPUnit - name your data sets in your data providers

Stuart Jones — Fri, 13 Mar 2020 01:07:32 +0000

Did you know that you can name the data sets in your data providers?

It might seem to be only decoration, but it can make life a little easier when reading both tests and test results.

Data providers are useful in that they allow us to repeat a single test with a range of inputs to ensure that we have covered various edge cases and user provided values. Unfortunately, having a large range of data sets in a provider can make it hard to keep track of what the purpose of each data set is for.

Say you have a form that is asking the user for values to set the font size, line height, and top and bottom margins of an element. These values are collected into a typography scale. You've enshrined your expectations in a validation rule, and now you want to test the logic in that rule. So, you have a couple of tests and providers like this:

/**
 * @test
 * @covers \App\Rules\Typography\Scale
 * @dataProvider provides_valid_scales
 */
public function passes_valid_scales($scale): void
{
    $rule = new Scale('body');

    $this->assertTrue($rule->passes('scale', $scale));
}

/**
 * @test
 * @covers \App\Rules\Typography\Scale
 * @dataProvider provides_invalid_scales
 */
public function fails_invalid_scales($scale): void
{
    $rule = new Scale('body');

    $this->assertFalse($rule->passes('scale', $scale));
}

public function provides_valid_scales(): array
{
    return [
        [
            [
                'font-size' => '1',
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
    ];
}

public function provides_invalid_scales()
{
    return [
        [
            [],
        ],
        [
            [
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        [
            [
                'font-size' => '-1',
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        [
            [
                'font-size' => '1.1.1',
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        [
            [
                'font-size' => 'a',
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        [
            [
                'font-size' => '1',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        [
            [
                'font-size' => '1',
                'line-height' => '1.25',
                'margin-top' => '1.25',
            ],
        ],
        [
            [
                'font-size' => '1',
                'line-height' => '1.25',
                'margin-bottom' => '1',
            ],
        ],
    ];
}

If you ran the tests and any of the conditions fail, you're just going to be told something like:

1) Test\Unit\Rules\Typography\ScaleTest::fails_invalid_scales with data set #0 (array())

2) Test\Unit\Rules\Typography\ScaleTest::fails_invalid_scales with data set #1 (array('1.25', '1', '1.25'))

3) Test\Unit\Rules\Typography\ScaleTest::fails_invalid_scales with data set #2 (array('-1', '1.25', '1', '1.25'))

Not very clear, is it?

Name your data sets

Naming your data sets provides two benefits:

The intent of the data set is clearer when you are looking at the test;
The failure report is more explicit.

public function provides_invalid_scales()
{
    return [
        'missing all properties' => [
            [],
        ],
        'missing font-size' => [
            [
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        'negative font-size' => [
            [
                'font-size' => '-1',
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        'multiple decimal points' => [
            [
                'font-size' => '1.1.1',
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        'non-numeric' => [
            [
                'font-size' => 'a',
                'line-height' => '1.25',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        'missing line-height' => [
            [
                'font-size' => '1',
                'margin-bottom' => '1',
                'margin-top' => '1.25',
            ],
        ],
        'missing margin-bottom' => [
            [
                'font-size' => '1',
                'line-height' => '1.25',
                'margin-top' => '1.25',
            ],
        ],
        'missing margin-top' => [
            [
                'font-size' => '1',
                'line-height' => '1.25',
                'margin-bottom' => '1',
            ],
        ],
    ];
}

And our failed tests:

1) Test\Unit\Rules\Typography\ScaleTest::fails_invalid_scales with data set "missing all properties" (array())

2) Test\Unit\Rules\Typography\ScaleTest::fails_invalid_scales with data set "missing font-size" (array('1.25', '1', '1.25'))

3) Test\Unit\Rules\Typography\ScaleTest::fails_invalid_scales with data set "negative font-size" (array('-1', '1.25', '1', '1.25'))

IDEs like PHPStorm will also use the data set name when reporting on PHPUnit results.

test results in PHPStorm

Sometimes even using the same name as the value in the data set can be helpful.

public function invalid_colors()
{
    return [
        '#123' => ['#123'],
        '#12345' => ['#12345'],
        '#1234567' => ['#1234567'],
        '123456' => ['123456'],

        'rgb(0, 0, 0)' => ['rgb(0, 0, 0)'],
        'rgba(0, 0, 0)' => ['rgba(0, 0, 0)'],
        'rgba(100, 100, 100, 1.00)' => ['rgba(100, 100, 100, 1.00)'],
        'rgba(256, 256, 256, 1.01)' => ['rgba(256, 256, 256, 1.01)'],
    ];
}

This is a little repetitive in the code, but failure messages will report with data set "rgb(0, 0, 0)" instead of with data set #4.

There you go - get naming today.

Laravel Database Factories for Better Testing

Stuart Jones — Wed, 04 Mar 2020 00:35:21 +0000

Automated tests are awesome. Having repeatable tests on your codebase to warn you if anything trippy has happened because of changes you've been making, and thereby helping to preventing the release of buggy code, is a lifesaver. They're also a bit of a pain sometimes, especially when testing code relying on a framework, since you sometimes need to bootstrap that framework as part of your tests.

When you're dealing with testing database interactions, you can experience even more pain. Not only do you have to restore state between each test, you also have to insert test data for many tests, which slows down tests and you can end up with a lot of setup prior to your actual test and assertions.

There are a number of strategies for speeding up testing, such as these general tips. Even database testing can be improved with functionality like Laravel's RefreshDatabase trait.

Database factories

Laravel provides database factories, which allow you to easily create fully populated data models within your tests, and reduce clutter within the test methods.

Say you have a simple table defined in a migration like this:

Schema::create('schools', function (Blueprint $table) {
    $table->bigIncrements('id');
    $table->string('name');
    $table->timestamps();
});

Assuming the data model to be App\School, you can create a database factory like:

$factory->define(School::class, function (Faker $faker) {
    return [
        'name' => $faker->sentence(),
    ];
});

Then in your test, you can write a single line:

$school = factory(School::class)->create();

And now you will have a model and a database record which can be manipulated and tested as needed. Even better, because the factory is using the Faker library, every school will have have a random name - reducing your tests' reliance on hardcoded strings and values.

If you want to just create a model without persisting it in the database, you can call the make method instead:

$school = factory(School::class)->make();

Related data and factories

Schools run courses, so we're going to create a courses table (and a Course model):

Schema::create('courses', function (Blueprint $table) {
    $table->bigIncrements('id');
    $table->bigInteger('school_id')->unsigned();
    $table->string('name');
    $table->timestamps();
});

Our Course model has the following relationship to the School model:

public function school()
{
    return $this->belongsTo(School::class);
}

Now, in order for our database factory to create a valid course, we need to set the school_id field, since it isn't nullable (courses must be attached to a school). The easiest, naive way is to do:

$factory->define(Course::class, function (Faker $faker) {
    return [
        'school_id' => 1,
        'name' => $faker->sentence(),
    ];
});

Unfortunately, this wouldn't also create the school, which may be important in some tests.

It is possible to inject/override values defined in the factory when using them to create or make models in your test. So, you could do something like:

$school = factory(School::class)->create();
$course = factory(Course::class)->create([
    'school_id' => $school,
]);

yes, that 'school_id' => $school, is correct - the factory knows how to resolve the ID from the school object.

In some tests, though, this could get a bit boilerplate, especially with complex/multiple relationships, and that boilerplate can get in the way of seeing what the test is doing/testing. Sometimes you can push it up to a setup method in the test case, but sometimes I'd rather just create a valid course along with it's relations in just the one line.

To do this, you can call other factories from within a factory:

$factory->define(Course::class, function (Faker $faker) {
    return [
        'school_id' => factory(School::class)->create(),
        'name' => $faker->sentence(),
    ];
});

Unfortunately, this brings a couple of problems. The first is that if you simply make a course instead of creating and persisting it, you will still create a database record for the school. The other problem is that, while you can still inject a school from your test, you'll end up with two school records being created (the one you create in your test and the one being made by the course's database factory which is then overridden).

/**
 * @test
 */
public function that_school_can_be_injected_into_course_factory()
{
    $school = factory(School::class)->create();

    $course = factory(Course::class)->create([
        'school_id' => $school,
    ]);

    // this will pass, since the school is actually overridden
    $this->assertEquals($school->id, $course->school->id, 'school was not overridden');

    // this will fail, since two schools are created
    $this->assertEquals(1, School::all()->count(), 'there are more schools than there should be');
}

the tests in this post are not what you'd normally bother writing - I'm just using them to highlight what's happening when you use the factories

This means there are 3 inserts into the database when there should have only been 2. That extra insert adds a little bit more time to the test, and that can add up across multiple tests.

Even worse, if you are creating multiple courses in a test:

/**
 * @test
 */
public function that_school_can_be_injected_into_course_factory()
{
    $school = factory(School::class)->create();

    $courses = factory(Course::class, 3)->create([ // create 3 courses
        'school_id' => $school,
    ]);

    // this will pass, since the school is actually overridden
    $this->assertEquals($school->id, $course->school->id, 'school was not overridden');

    // this will fail, since four schools are created
    $this->assertEquals(1, School::all()->count(), 'there are more schools than there should be');
}

In this case, 4 schools will have been inserted into the database, when we only wanted 1.

Fixing things by getting lazy

There's a method available to database factories that isn't covered in the documentation - the lazy method.

Basically, this method tells the factory to create a model/record, but only if it has to.

$factory->define(Course::class, function (Faker $faker) {
    return [
        'school_id' => factory(School::class)->lazy(),
        'name' => $faker->sentence(),
    ];
});

Using the lazy method like this means that we can override the school for the course without creating redundant data. Both of the following tests will pass when we use this method.

/**
 * @test
 */
public function that_a_school_is_created_by_course_factory()
{
    $course = factory(Course::class)->create();

    $this->assertEquals(1, School::all()->count(), 'there are more schools than there should be');
    $this->assertEquals(School::first()->id, $course->school->id);
}

/**
 * @test
 */
public function that_school_can_be_injected_into_course_factory()
{
    $school = factory(School::class)->create();

    $courses = factory(Course::class, 3)->create([
        'school_id' => $school,
    ]);

    $this->assertEquals($school->id, $courses->first()->school->id, 'school was not injected');
    $this->assertEquals(1, School::all()->count(), 'there are more schools than there should be');
}

The limit on the lazy method is that it will still create a school and persist it if we don't provide an override, even if we don't persist the course.

/**
 * @test
 */
public function that_school_is_not_created_if_course_is_not_persisted()
{
    factory(Course::class)->make();

    $this->assertEquals(0, School::all()->count(), 'there are more schools than there should be');
}

I assume the reason is that the only way for the factory to get a valid school ID to inject into the course is for there to be an actual school record in the database to provide the auto-generated ID. I don't think that this is necessarily a requirement - the only time school_id must be correct and valid is when we save the course - which we might not be doing in our test. However, then we would have to have our factory somehow detect that we are saving the course in order to generate the school record and retrieve an ID.

Something to think about?

Finishing up

Database factories are very helpful. The lazy method, makes it possible to reduce unnecessary database inserts during the lifetime of tests. As I said, the amount of time saved in a single test is pretty small, but this can add up when you have a lot of tests relying on the database.