DEV Community: Josh Britz

Creating a Useful Component Library

Josh Britz — Wed, 05 Aug 2020 13:39:23 +0000

One of the great benefits of the many SPA frameworks that we use nowadays (such as Angular and React) is that it is super easy to make reusable UI components that are clean and self-contained. Components that built in these frameworks are easier to debug and far more reliable than the traditional sort of component. We can create a project with something like the Angular CLI and have a nice little directory for the components we are using in our app and it's all hunky-dory from there. If a component is not working, you simply have to make a change in one place and the problem is sorted all across your app. Now, this is great for a project where the components you have will only be used in one application. We do, however, run into some major issues when it comes to a situation where you need to use the same components for multiple, separate projects.

This is where component libraries really shine. You can have your set of components hosted on a repository like npm and whenever you need to use them in your application. The solution is simple, the method is less so. You see, it is very easy to just throw up a couple of components in an npm package and call it a day. However, if you want to have a component library that is a tool that developers love using, there are a few things that you should keep in mind.

Build up a culture of education around the process

Often times a component library becomes the sole propriety of a single developer (or at least a single team of developers) in a company. This is a big problem, especially when things go wrong. If you happen to be in a position where you are managing a component library for your company, the best thing you can do for yourself and your team is put a ton of effort into educating the people that will use the component library. Teach them about the process of creating components. Teach them about how components are named and what classifies as a component. Teach them how to even make their own components. When you do this, you are not only helping to upskill your co-workers, but you are helping them to be better equipped to implement and debug the components you create.

Don't try to protect your precious code or your knowledge. You may feel like teaching someone about the in's and out's of your job may put your own position at risk, but more often than not it will actually be a sign that you are actually good at what you do.

Work very closely with your designers

To build good components, you must become the components, you must think like the components... Or at least, you must get a good idea of what the components' creators thought process was when creating components. I was involved in a project not too long ago for a bank (we'll call them NextBank) where we did a complete revamp of their corporate site, design, code, the works. Because of this, we ended up creating a lot of new components. But we did this is a rather impractical way. An example of this was with the card components we created. There was not a lot of discussion with the designers (or at least not enough) through the building of the components and so by the time we started to build out pages, we discovered that we had 7 different card components, each with their own styles and use cases. However, after discovering this fact, we started actually speaking to the designers and managed to figure out what was the goal and motivation behind the design variations. We were then able to consolidate the components and even get rid of some of the completely because we were able to advise the designers about where they were creating unneeded duplication (there were a lot of cards that were only different visual, and only but a small degree).

If you want to build a good component library, make sure that you build a good relationship with your designers. Allow them to explain their thought process to you and try to understand what that want to achieve with each of the components that they have designed, and why they designed them the way they did. You'd be surprised how valid some of their rationales are. Get to know as much as you can about a component before you start to build it.

Do not make everything a component

The is a line from the movie The Incredibles that I always love. The villain Syndrome is talking to Mr Incredible about how he is going to give everybody superpowers, and finishes by saying "..when everybody's super, then no one will be...". We should adopt a similar attitude towards components. Not everything needs to be a component and in fact, when you try to make everything into component, your app just becomes unmanageable. A good rule of thumb here is to wait until you see a UI pattern being used three or more times in a single application, or any number of times across more than one application. It can help to create a distinction between what I call external components and internal components. Internal components are components that are created within and applications code. They are easy to change and updated, but can only be used in the application where they have been built. Internal components can be promoted to external components at a later if you feel they meet your requirements (as in my example, if it is being used more than twice or in more than one project). Remember, internal components are easy to change and even remove because they do not have a lot of code depending on them. Try to start all your new components as internal components before making them into external components.

External components are components that are hosted outside of the project they are being used in and come with a high degree of stability and reliability. They are not going to change often, and when they do, the process is slow and easy to manage. External components will be a collection of very common UI patterns that appear across multiple projects within a brand. To go back to the example of NextBank, we had 6 different projects we were working on for them that all used the same basic set of components. It absolutely saved our lives to be able to fix bugs in one place and watch each of the projects that used the component library get fixed right away. We did, however, get to a point where everything was being made into a component in that component library (even if it only appeared in one place across all 6 projects). This made our code unmanageable and slowed down our process unnecessarily when those components need to be fixed.

Think twice, think again, then start building.

Building a good component library takes a lot, and I mean a lot of planning. It's easy to build components. The trick is in building them right. Remember that when you build a component library and those components start getting used, you cannot remove them or change them drastically for fear of breaking a project's code. Even changing something as simple as a variable name can break an entire applications build system. It's wise to try to think through as many possible use cases as you can for the component you are trying to build. Make sure you know what you will call everything, how you want the component to work, how other developers will interact with it and use it, and how it will look and work on different screen sizes. Also, think about how its functionality might be changed. Will the developers who use this component be able to use it in every case they may need to use it in? Or are they going to have to hack around you code just to get it to work so that they can get the page into QA?

Think, think, think. Always ensure that your component library has a well thought out structure that will survive the tests of time and use.

Keep content out of it

There is nothing more frustrating than trying to use a component that you need only to find that is was created for a specific page and comes prepacked with copy and an image that will not work for your use case. Always keep your components (especially external components) content-agnostic. If they are meant to contain or hold content, build that into the component, but make sure that that content can be provided on a "per instance" basis. This does often fall under the same sort of idea as making sure you are not making everything into a component and making sure you are planning your components, but it deserves its own spot because it can be a very big issue. It may seem obvious to some, but components should never contain page-specific copy, images, or icons. I'd even go as far as to say that any copy you have in a component should, at the very least, be customisable.

Final Words

Components libraries are great. I love building them and I love using them. However, they are deceptively difficult to do right. I hope this article gives some good insights into how you can build better components libraries for your component, based on what I have learned from my experience. Good luck and happy coding.

An Opinion on Progressive Enhancement in CSS

Josh Britz — Tue, 07 Apr 2020 05:13:31 +0000

Although support for the "plague browsers" is dropping by the year, developers across the world are faced with the challenge of having to support older web browsers like Internet Explorer. Such browsers have very limited support for new web technologies like grid, flexbox, or custom properties. Because of browsers like this, the CSS spec gives specific instructions to browsers about how they should treat CSS rules that they do no understand. That is, that browsers should discard any line of CSS they do not understand. For example, let's look at the below selector that uses logical properties.

.box {
   padding-inline: 30px;
   margin-block: 30px;
}

In a browser that understands logical properties, the .box element will get padding of 30px on the left and right and a margin on the top and bottom of 30px. However, a browser that doesn't understand logical properties will completely ignore those rules and the element will have no padding or margin. Thankfully, CSS has an elegant around this issue: the @supports selector. With our above example, we might use @supports like this.

.box {
   padding-left: 30px;
   padding-right: 30px;
   margin-top: 30px;
   margin-bottom: 30px;

   @supports (padding-inline: 30px) and (margin-block: 30px) {
      padding-inline: 30px;
      margin-block: 30px;
   }
}

Essentially, what's happening here is that the .box selector gets the standard, well-supported padding properties in all browsers. However, in a browser that supports logical properties, the element will get the logical property rules. This is an elegant way of handling progressively enhanced pages by using CSS rules that work in all browsers and then overwriting those rules with newer, less-supported rules by wrapping them in @supports blocks.

But, here's the rub. When should you actually use @supports? When we build things with CSS, there will always be a browser that has lower levels of support for CSS features than others. Because of the nature of CSS, rules that work on an old browser have to work on newer browsers in order to maintain backwards compatibility. So if we are creating a layout and we have to support a browser that only understands Float Layout for instance, then it is fully possible to build a layout that will work in all browsers even if they have support for newer technologies (like flexbox). The question then is this: "If you can build something with an older CSS technology, what is the point of rewriting styles with newer tech to redundantly achieve the same results?"

When deciding on which CSS feature to use for a project or design, here are some things that I think should be considered.

The CSS technology you choose should have the widest browser support while still being able to do as much of what you need as is possible.

Now you must know, I am a hipster at heart. Whenever new CSS features are released, I immediately want to try out that new feature and then brutally smash it into the projects I'm working on. However, recently I've tried to reform my thinking in this area. I used to spend hours upon hours rewriting and bug fixing my CSS so that it would work in IE because the shiny new features I'd got working in Chrome using the shiniest and newest CSS, were not at all supported.

But there is a simple way around this problem. Instead of just opting for the thing that makes you code look sleeker and lets you write your code with less effort, consider rather finding the feature that has the widest support for the most browsers while still being able to do what you need. Your aim should be to write as little fallback CSS as you possibly can. Here is an example of this problem in the real world.

.container {
   width: 100%;
   height: auto;
   padding: 40px;
}

.container::after {
   content: '';
   display: table;
   clear: both;
}

.container .box {
   float: left;
   width: calc(50% - 20px);
   height: 200px;
   border solid 2px pink;
}

@supports (display: flex) {
  .container {
     display: flex;
     flex-flow: wrap row;
     align-items: stretch;
  }

  .container .box {
     flex: 1;
     max-width: calc(50% - 20px);
  }
}

This code will produce something like this.

Awesome, so this code works! However, you could remove the @supports part of the above code and it would work perfectly fine, in all browsers. In fact, we can decrease the size of our CSS file by removing it. Does this then mean that you should go through all your CSS from all your projects and delete any fallback CSS you can find? Absolutely not! While there is a large amount of redundant CSS out there, there is another factor to consider when you face the issue of write fallback (or progressively enhanced) CSS: Accessibility.

Please always consider the accessibility of the CSS features you want to use.

It's well and all saying that you shouldn't use a CSS feature just because it's shiny and new, and that you should try to use features that have the widest support across the board. However, it would be wrong to throw out progressively enhanced code altogether. Some of the older CSS features out there require you to order your HTML elements in an illogical or impractical way. This can result in HTML pages that screen readers are unable to parse or sites that are frustrating to those who navigate pages using keyboards. So, when picking a CSS feature you want to use, you need to ensure that you pick a feature that has the best accessibility that you can find even if it means that you may have to write some fallback CSS for browsers that do not understand the feature.

You want to find a good balance between support of a feature and its accessibility, which may mean writing a little extra CSS for your edge case browsers so that your site works properly. Consider the example I used earlier:

.box {
   padding-left: 30px;
   padding-right: 30px;
   margin-top: 30px;
   margin-bottom: 30px;

   @supports (padding-inline: 30px) and (margin-block: 30px) {
      padding-inline: 30px;
      margin-block: 30px;
   }
}

The code is guaranteed to work in all browsers because all browsers support the standard padding properties very well. However, not all browsers understand the much newer standard of logical properties (you can find a good explanation of what their benefits are here). Yet, because logical properties offer us better internationalization they are a better choice for us as they will make our site more accessible to more people. In this case the benefits outway the drawbacks.

Now let's look at the other example I used.

.container {
   width: 100%;
   height: auto;
   padding: 40px;
}

.container::after {
   content: '';
   display: table;
   clear: both;
}

.container .box {
   float: left;
   width: calc(50% - 20px);
   height: 200px;
   border solid 2px pink;
}

@supports (display: flex) {
  .container {
     display: flex;
     flex-flow: wrap row;
     align-items: stretch;
  }

  .container .box {
     flex: 1;
     max-width: calc(50% - 20px);
  }
}

This is an unnecessary progressive enhancement. Any browser, new or old, will understand float layout and the boxes do not display differently when flexbox is used. That extra code is therefore not needed and can be removed from your project without worry.

Ensure that your time is being well spent.

Another consideration when deciding on whether or not to progressively enhance your CSS is time. Your time as a developer is very valuable and you should be doing as much as you can to optimize and utilize that time.

When you are trying to build a feature with CSS, you need to find a solution that takes up the least amount of your time. It is very time-consuming to write tons of fallback CSS in order to get your code to work on browsers like IE.

So, what can be concluded from the rant of an article? I'm not trying to say that you shouldn't use new CSS or that you should only use old CSS. Rather, I want to advocate that you take time to consider the CSS you use for projects. Don't just automatically opt for new shiny CSS for its own sake as nice as it is.

The Sexiness of Headless UI Components

Josh Britz — Mon, 02 Dec 2019 06:46:15 +0000

Something I enjoy doing most on the web is creating things that help other developers to be more productive. I especially love creating component libraries and core development kits that can be used to make project bootstrapping and deveopment easier. As a result I have spent a substantial amount of time trying to find newer and better ways of making sure that the components I make are robust, versatile, and easy to use. One of the things I've noticed about components is that we developers have a natural tendency of just make them work in the given immediate use case or context. So often we incorporate business logic, layout logic, and other specifics as part of the component's makeup. Many components are just abstracted into a separate project from where they are being used, but take no advantage of the benefits provided by doing that. One of the biggest reasons for this, in my opinion, is that components are way too tied to the design iteration they represent. They are made to cater for the designs that can be found at the time of them being made, but have no mindfulness of future enhancements. There have been many times when I've poured hours into making components that work according to specification, look good, are well tested, and have proper documentation. Yet the very next day, I'll get to work only to find that the design has changed or a new use case had been added and so the component has to be updated. This is very frustrating and is the cause of a lot of (often) easily avoidable bugs.

So what's the solution? If your read the title I'm sure you will be able to guess what I'm going to say next. Headless UI Components. But what are those? Well, to sum it up Headless UI Components are Components that provide a set of functionalites for a feature without explicitly determining its UI aspect. Let's look at an example of what I mean. The follwing example is not a Headless Component.

const Counter: FC = () => {
   const [count, setCount] = useState(0);

   return (
     <div className="counter-wrapper">
       <button onClick={() => setCount(count - 1)}>-</button>
       <span>{count}</span>
       <button onClick={() => setCount(count + 1)}>+</button>
     </div>
   );
}

Now it should be quite easy to see what's happening here. We have a component state (thanks to React Hooks) and a component UI. The UI is made up of two buttons for incrementing and decrementing the count value and an output to see what the value is. This works fine and does what its supposed to. However, we are limited to the UI that the component provides for us. Let's say we want to change the text in the buttons to say more and less rather than + and -. We could add some props to the component to do that.

interface Props {
  decrementText?: string;
  incrementText?: string;
}

const Counter: FC<Props> = (props: Props) => {
  const [count, setCount] = useState(0);

  const {decrementText = '-', incrementText = '+'} = props;

  return (
    <div className="counter-wrapper">
      <button onClick={() => setCount(count - 1)}>{decrementText}</button>
      <span>{count}</span>
      <button onClick={() => setCount(count + 1)}>{incrementText}</button>
    </div>
  );
};

Cool! It works. No Sweat. But, now let's say we need to change how much we increment/decrement the counter by each time we click the button. We would need to add yet another propety to our component.

interface Props {
  decrementText?: string;
  incrementText?: string;
  stepAmount?: number;
}

const Counter: FC<Props> = (props: Props) => {
  const [count, setCount] = useState(0);

  const { decrementText = '-', incrementText = '+', stepAmount = 1 } = props;

  return (
    <div className="counter-wrapper">
      <button onClick={() => setCount(count - stepAmount)}>
        {decrementText}
      </button>
      <span>{count}</span>
      <button onClick={() => setCount(count + stepAmount)}>
        {incrementText}
      </button>
    </div>
  );
};

At this point, we have a component that does 4 things.

It allows you to increment its value
It allows you to decrement its value
It allows you to configure some of it's properties
It renders some UI to reflect its state

Now this may even be exactly what you want from your component (and there are certainly times when something like this will be your best bet). However, as you can see, each change we want to make to the component's UI has to be pre-planned and built into the component. It also gets messier with each new state or option you add.

So what if I want the functionality of the counter (its state, and ability to increment and decrement), but not the UI that is given. In most cases, the solution is to just build a new component that works in the same way as an exsisting component, but render a different UI or, to add another config to the component's props that switches between the two UIs.

But... There is another way. Enter Headless UI Components. Hopefully at this point you can see a use case for a component that provides the functionality you need without caring about it's UI. Let's look at how this would work.

interface Arguments {
  count: number;
  increment: (value: number) => void;
  decrement: (value: number) => void;
}

const Counter = (props: { children: (args: Arguments) => JSX.Element }) => {
  const [count, setCount] = useState(0);

  if (!props.children || typeof props.children !== 'function') return null;

  return props.children({
    count,
    increment: (value: number = 1) => setCount(value),
    decrement: (value: number = 1) => setCount(value),
  });
};

🤨 what is that?! Admittedly, this code doesn't look super sexy compared to the example we saw before. But, it can do so much more. Because it doesn't control its own UI you can plug any UI you want into it and use its functionality as you want. Below is an implementation of the component that is similar to the non-headless variant.

<CounterHeadless>
  {({ count, increment, decrement }: any) => {
    return (
      <div className="counter-wrapper">
        <button onClick={() => decrement(count - 1)}>less</button>
        <span>{count}</span>
        <button onClick={() => increment(count + 1)}>more</button>
      </div>
    );
  }}
</CounterHeadless>

Or something with a different layout.

<CounterHeadless>
  {({ count, increment, decrement }) => {
    return (
      <div className="counter-wrapper">
        <h2>{count}</h2>
        <button onClick={() => decrement(count - 1)}>-</button>
        <button onClick={() => increment(count + 1)}>+</button>
      </div>
    );
  }}
</CounterHeadless>

Or with just the increment function.

<CounterHeadless>
  {({ count, increment }: any) => {
    return (
      <div className="counter-wrapper">
        <h2>{count}</h2>
        <button onClick={() => increment(count + 1)}>+</button>
      </div>
    );
  }}
</CounterHeadless>

The possiblities for this component, though not endless, are much greater because its UI can be whatever you need it to be (sort of the Batman of components). With Headless Components, you can easily package common utilities for various components and ship them without even having to think about how much padding this button must have, or what color that border will be, or if the border-radius of the other thing should be 5px or 3px. You can simply create a robust component that does everything you need it to, and worry about the UI when you get to actually using the component.

So what about components that need to be styled in a specific way?. A common use case for components is to have pre-styled and tested design elements that can be dropped into a page without having to worry about their styling. The problem is, headless components don't let you do that... Or do they? Just because you make use of headless components doesn't mean that you should never build components that have UI. In fact headless components can make this process even easier. If we take the example of the counter above, we can see that we have created a few different variations of that counter. Using the headless counter component we built, we can make each of these counters into their own component without having to duplicate functionality accross components.

const Counter: FC = () => {
  return (
    <CounterHeadless>
      {({ count, increment, decrement }) => {
        return (
          <div className="counter-wrapper">
            <button onClick={() => decrement(count - 1)}>less</button>
            <span>{count}</span>
            <button onClick={() => increment(count + 1)}>more</button>
          </div>
        );
      }}
    </CounterHeadless>
  );
};

const CounterStacked: FC = () => {
  return (
    <CounterHeadless>
      {({ count, increment, decrement }) => {
        return (
          <div className="counter-wrapper">
            <h3>{count}</h3>
            <button onClick={() => decrement(count - 1)}>less</button>
            <button onClick={() => increment(count + 1)}>more</button>
          </div>
        );
      }}
    </CounterHeadless>
  );
};

const CounterLabeled: FC<{ label: string }> = ({ label }) => {
  return (
    <CounterHeadless>
      {({ count, increment, decrement }) => {
        return (
          <div className="counter-wrapper">
            <h3>
              {label} - {count}
            </h3>
            <button onClick={() => decrement(count - 1)}>less</button>
            <button onClick={() => increment(count + 1)}>more</button>
          </div>
        );
      }}
    </CounterHeadless>
  );
};

export { CounterLabeled, Counter, CounterStacked };

And there you go. Three components for the price of one. You can use each one of the above counters as preset components in your app or, if you need to, you can just use the headless base version and create your own variation.

In my opinion, components are way too tied to specific designs. Many components you'll find today are mangled cesspools of uneeded configurations, business logic, and styling. We spend so much time creating components that look and work exactly according to specififcation only to have to overwrite so much of our work because one of the designers thought it would be "cooler" if the arrow was on the other side of the button on this page. Overall, I think that headless components are a great way of getting around this problem as well as many others that we face when creating components.

The code from this article is in the following GitHub repo, so feel free to play around with it.

joshuapbritz / SexyHeadlessComponents

Demo of Headless UI Components with React

Why it's so hard to check object equality in JavaScript

Josh Britz — Tue, 19 Nov 2019 06:35:46 +0000

The other day I was working on a bit of code where I found myself having to check if two JavaScript objects were equal, namely, do two objects have the same keys and values. The first thing I tried was putting them into a simple equality check (using ===) and thought that my problem was solved. However, it turns out that comparing JavaScripts objects is much harder than I thought.

I spent quite a bit of time trying to find a solution to this problem that covered all the edge cases so I decided to write an article about it. I hope my findings will be helpful.

A Breakdown of the Problem

So that we are on the same page, I'm going to quickly break down what the issue is with a quick example:

const a = { name: 'simple object' };
const b = a;

console.log(a === b); // -> true

const c = { name: 'simple object' };

console.log(a === c); // -> false

Huh? That doesn't seem right. Both a and c look like they are equal. However, comparing them together using === we get a false value.

So why does this happen? Well, the main reason this happens is that (===) doesn't check that both objects have the same property keys and values. Instead, it checks that the two objects occupy the same place in memory. Hence, when we declare a it is given a place in memory. When we assign a to b, we are not declaring a new object, rather we are telling b that its value is in the same location as a. So essentially, when we do a === b, it returns true because we are essentially doing a === a (which is obviously going to be true).

However, when we take a (its value being { name: 'simple object' }) and compare it to a new object that looks the same (a === c), we get false. The reason this happens is that the object we assigned to c occupies a different place in memory than a. Therefore, when === tries to check if the two objects are the same place in memory, it returns false because they are in different places in memory.

An interesting little side note here is that when we assign a to b, we can actually change properties in b and yet it will still be equal to a using ===.

const a = { name: 'simple object' };
const b = a;

console.log(a === b); // -> true

b.name = 'Changed Name';

console.log(a === b); // -> true

console.log(a); // -> { name: 'Changed Name' }
console.log(b); // -> { name: 'Changed Name' }

Because b simply references variable a's place in memory, changing a value in b also changes that value in a.

So What's the Solution?

I spent a fair amount of time trying to find a good solution to this problem and found a few different solutions that do work. Because the use cases you might have are different, I will show a few of the solutions I found and give a brief explanation of each.

Solution 1 - JSON.stringify

If you have a fairly simple object, it is quite easy to use JSON.stringify to check if they are equal.

const a = { name: "Joshua" };
const b = { name: "Joshua" };

console.log(a === b); // -> false

console.log(JSON.stringify(a) === JSON.stringify(b)); // -> true

This works, but it is not very reliable. It will require that all your keys and values are in the same order, otherwise, it will see the two objects as unequal.

const a = { name: "Joshua", surname: "Britz" };
const b = { surname: "Britz", name: "Joshua" };

console.log(JSON.stringify(a) === JSON.stringify(b)); // -> false

This method is not recommended but can work in certain situations.

Solution 2 - Shallow Key/Value check

This solution should work for a large number of cases. We simple extract the keys from our object, make sure that they match, and then check if the values of those keys match as well.

const a = { name: "Joshua", surname: "Britz" };
const b = { surname: "Britz", name: "Joshua" };

function areTheseObjectsEqual(first, second) {
  const al = Object.getOwnPropertyNames(first);
  const bl = Object.getOwnPropertyNames(second);

  // Check if the two list of keys are the same
  // length. If they are not, we know the objects
  // are not equal.
  if (al.length !== bl.length) return false;

  // Check that all keys from both objects match
  // are present on both objects.
  const hasAllKeys = al.every(value => !!bl.find(v => v === value));

  // If not all the keys match, we know the
  // objects are not equal.
  if (!hasAllKeys) return false;

  // We can now check that the value of each
  // key matches its corresponding key in the
  // other object.
  for (const key of al) if (first[key] !== second[key]) return false;

  // If the object hasn't return yet, at this
  // point we know that the objects are the
  // same
  return true;
}

console.log(areTheseObjectsEqual(a, b)); // -> true

Solution 3 - Deep Equals.

So solution two works, but it has limitations. It will work fine if your object is fairly flat in its structure. But when we get to more complex objects with nested values, it fails badly. So, we need a better solution for cases like this. Here is the solution I ended up using:

const a = {
  name: "Joshua",
  surname: "Britz",
  pets: [
    { type: "cat", name: "Florence" },
    { type: "cat", name: "Da Vinci" }
  ]
};

const b = {
  surname: "Britz",
  name: "Joshua",
  pets: [
    { type: "cat", name: "Florence" },
    { type: "cat", name: "Da Vinci" }
  ]
};

function areTheseObjectsEqual(first, second) {
  "use strict";

  // If the value of either variable is empty
  // we can instantly compare them and check
  // for equality.
  if (
    first === null ||
    first === undefined ||
    second === null ||
    second === undefined
  ) {
    return first === second;
  }

  // If neither are empty, we can check if
  // their constructors are equal. Because
  // constructors are objects, if they are
  // equal, we know the objects are of the
  // same type (though not necessarily of
  // the same value).
  if (first.constructor !== second.constructor) {
    return false;
  }

  // If we reach this point, we know both
  // objects are of the same type so all
  // we need to do is check what type one
  // of the objects is, and then compare
  // them
  if (first instanceof Function || first instanceof RegExp) {
    return first === second;
  }

  // Throught back to the equlity check
  // we started with. Just incase we are
  // comparing simple objects.
  if (first === second || first.valueOf() === second.valueOf()) {
    return true;
  }

  // If the value of check we saw above
  // failed and the objects are Dates,
  // we know they are not Dates because
  // Dates would have equal valueOf()
  // values.
  if (first instanceof Date) return false;

  // If the objects are arrays, we know
  // they are not equal if their lengths
  // are not the same.
  if (Array.isArray(first) && first.length !== second.length) {
    return false;
  }

  // If we have gotten to this point, we
  // need to just make sure that we are
  // working with objects so that we can
  // do a recursive check of the keys and
  // values.
  if (!(first instanceof Object) || !(second instanceof Object)) {
    return false;
  }

  // We now need to do a recursive check
  // on all children of the object to
  // make sure they are deeply equal
  const firstKeys = Object.keys(first);

  // Here we just make sure that all the
  // object keys on this level of the
  // object are the same.
  const allKeysExist = Object.keys(second).every(
    i => firstKeys.indexOf(i) !== -1
  );

  // Finally, we pass all the values of our
  // of each object into this function to
  // make sure everything matches
  const allKeyValuesMatch = firstKeys.every(i =>
    areTheseObjectsEqual(first[i], second[i])
  );

  return allKeysExist && allKeyValuesMatch;
}

console.log(areTheseObjectsEqual(a, b)); // -> true

This method will cover most use cases and is fairly reliable. There is one caveat that I am aware of, and that is that it does have a dependency on the order of your arrays.

const one = [1,2,3,4];
const two = [4,3,2,1];

console.log(areTheseObjectsEqual(one, two)); // -> false

If you need to check array equality, you may need to look at a different solution.

Solution 4 - Use a library (😱🙀🤯)

Now, I'm not advocating for the use of external packages for every situation. The above three solutions will most like work for the majority of situations you come across. However, if you are already using a library that has support for this, or the need you have can justify adding a package to your app, there are definitely very good solutions out there. I won't go into all of them, but a good one that I know of is loadash's _.isEqual method (https://lodash.com/docs/4.17.11#isEqual).

I'm interested to know what other developer's solutions are to this problem. If you have a method that you use, please feel free to share in the comments.

6 principles to make your projects more "team friendly"

Josh Britz — Thu, 07 Nov 2019 14:00:57 +0000

The other day I was reflecting on the team that I am currently working with on a massive project at our company. We have recently gone through a huge overhaul in our process and structures, so I wanted to see how those changes had reflected in projects. Namely, I wanted to try and see what we did well, what maybe needed some work, and what we needed to start (or stop) doing.

In thinking about this, I decided to turn my findings into an article outlining our team's goals and principles (whether or not we are perfectly achieving them or not). These are very subjective ideas that are tailored to the team I work with. So while I hope you can draw some benefit from how we as a team think, please don't take any of these principles as set-in-stone rules.

1: Have a clearly defined project structure and style guide

There are hundreds if not thousands of different views, held by many respectable developers, on what good code looks like. There is a style guide for everyone's preference, ranging from very unopinionated and general to highly opinionated and detailed. Now, there is nothing particularly wrong with either approach. As a developer (on your own) you have the right to any preference in code style you want. If you like strongly typed and ultra-explicit nature of TypeScript code, cool. Or maybe you prefer that slightly more lenient and free nature of vanilla JavaScript instead, also cool. We are all different people with different ways of thinking and organising our minds, and the way we right code should reflect that.

However, when we have to work with a team, things change a little bit. When you get to a point where you are writing code with other people, the reason for having a style guide changes a little bit. No longer is the question "what is your preference?" or "how do you like to write code?", rather you have to ask "how can my code be written so that anyone on my team can easily work on this?" or "how can my team write code in such a way that our codebase looks like one person wrote it?". When working in a team you will often have to pick up tasks that your co-workers started, or you will have to fix bugs in parts of an application that you have never worked on. This is when a coding standard is most vital. If you have rules that determine how to name variables and functions, where to place code in your files, how to name your files and whatever else you might have rules for, you and your team will find it much easier to work on code that you have never worked on before.

2: Define project scripts in an easy to access place

So many times you will have to work on a project where the build scripts for that project are nowhere to be found. This is a small thing but it can save developers so much time. If you are using any sort of NodeJS tool, this is super simple to do. All you have to do is add items to the scripts section of your package.json. It may seem like something so simple and trivial, but it makes things so much for the other developers in your team.

3: Make sure you have a readme file

Many projects you'll come across will not have a proper readme file. In most cases, most often with projects generated by a CLI, the readme file that can be found in the project is completely unuseful. The technical information is generic and out of date, the setup steps are sorely lacking and any developer looking to get going on that project is left to fend for themselves in the maze of code they have found in the repo.
Your readme is meant to be the starting point for developers going into a project and should provide the following information:

A brief (like extremely brief) intro to the project.
A list of links to the relevant documents, specs, repositories, and other places where developers can learn more about the project. Also, if available, include a link to where the live version of the project is hosted.
An up to date list of the environments needed to run the project, including:
- Languages that need to be installed (with versions specified if important)
- Build tools and CLI tools that need to be installed
- CI/CD and DevOps tools being used
And, a list of steps that are needed to run, build or deploy that project.

4: Don't use flashy code, use readable code.

Readable code is better than succinct code... every time. This is not to say that you should be writing messy code or inefficient code. Rather, when choosing how you are going to solve a problem it is a great temptation to try and make your code as compact as you possibly can. I've often caught myself writing one-liners that do solve the problem I'm trying to solve but also are virtually unreadable for anyone other than me. But when working with a team, you should prioritize the readability of your code. What could even be best practice or at least completely fine code for you to write in your own projects, could mean hours that another dev, unfamiliar with that pattern or idea, could spend trying to work with that code. Often it is best to discuss with your team and make decisions on what sorts of code you will use and what you will not.

5: Add comments to your code

This may be one of the most hotly debated things in code. Between those who say that code should be covered from top to bottom with comments to those who say code should have no comments and that code should document itself, it is hard to know what to think. However, it is my opinion that when we are working teams, you cannot always be sure that you are going to be the one to maintain the code you have just written. Bugs will be raised and someone will have to fix them and more often than not, it won't be you. This is what comments are for. They can be a very useful tool in ensuring that that next person who works on your code can see what you were thinking when you wrote it.

That being said, please don't go writing mini novels above each line of your code. All you really need from a comment is a piece of a map that points to the flow of the code you have written. This may be a justification for calling a function, and explanation of a hack or detailing of logic. A good question to ask yourself when writing comments is "what do I wish I had known before writing this code?".

6: DO NOT try to implement any of the above apart from your team.

These points are things I have found from my own experience in my own team and may not be the solution for everyone. They are not rules, but rather principles that should be adapted to suit your team. Further, they are principles that pertain to your whole team. If you feel that your team should be implementing some of these things, don't just bulldoze through and try to implement them in your own power. Get your team together, talk about how you would go about implementing these changes as a team and discuss the pros and cons of each change. Decide together whether or not any or all of these principles are going to benefit your team. Each team is different and has its own needs so you should treat yours that way.

Create a Keybinding Service in Angular

Josh Britz — Wed, 06 Nov 2019 14:54:55 +0000

A common frustration I come across when working with Angular (or any other framework for that matter), is running functions based on key bindings. The typical method of doing this is unreadable and messy. For example, if you wanted to run a function when a user hit CTRL+ALT+D, your code would look something like this.

window.addEventListener('keydown', (event: KeyboardEvent) => {
   // Fall back to event.which if event.keyCode is null
   const keycode = event.keyCode || event.which;
   if (keycode === 68 && event.ctrlKey && event.altKey) {
     // Do stuff here
   }
});

True, it could be worse. Never the less, doing this can become very messy
very quickly. It is also difficult to quickly find and fix problems because you have to know the exact number of each key code to know what key command is being listened for. In a recent project, I was working on, I decided to remedy the issue by abstracting the process into an Angular service and now I'm going to show you how to do it.

Creating a project

Because we are making an Angular service, you will need to have an Angular project to work in. You can use an existing one, or you can create a new blank project to play around with.

$ ng new KeyBindServiceApp

You should now have a fresh project to work in.

Setting things up

First of all, we need to create a service that will do all our work.

$ ng g service path/to/services/key-bind

Your newly created service should look something like this.

import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root'
})
export class KeyBindService {
  constructor() { }
}

In the same folder as your service, create two new files: one called modifiers.ts and one called keycodes.ts, and copy the following code into them. You can move these later, but for now, it is easier to keep them in the same folder as your service.

/**
* Checks if an event has any of the provided
* keycodes
* @param {KeyboardEvent} event
* @param {Array<number>} codes
*/
export function hasKeycode(event: KeyboardEvent, codes: number[]): boolean {
  return codes.some(value => (event.keyCode || event.which) === value);
}

export const KEYS = { A: 65, ALT: 18, APOSTROPHE: 192, AT_SIGN: 64, B: 66, BACKSLASH: 220, BACKSPACE: 8, C: 67, CAPS_LOCK: 20, CLOSE_SQUARE_BRACKET: 221, COMMA: 188, CONTEXT_MENU: 93, CONTROL: 17, D: 68, DASH: 189, DELETE: 46, DOWN_ARROW: 40, E: 69, EIGHT: 56, END: 35, ENTER: 13, EQUALS: 187, ESCAPE: 27, F: 70, F1: 112, F10: 121, F11: 122, F12: 123, F2: 113, F3: 114, F4: 115, F5: 116, F6: 117, F7: 118, F8: 119, F9: 120, FF_EQUALS: 61, FF_MINUS: 173, FF_MUTE: 181, FF_SEMICOLON: 59, FF_VOLUME_DOWN: 182, FF_VOLUME_UP: 183, FIRST_MEDIA: 166, FIVE: 53, FOUR: 52, G: 71, H: 72, HOME: 36, I: 73, INSERT: 45, J: 74, K: 75, L: 76, LAST_MEDIA: 183, LEFT_ARROW: 37, M: 77, MAC_ENTER: 3, MAC_META: 224, MAC_WK_CMD_LEFT: 91, MAC_WK_CMD_RIGHT: 93, META: 91, MUTE: 173, N: 78, NINE: 57, NUM_CENTER: 12, NUM_LOCK: 144, NUMPAD_DIVIDE: 111, NUMPAD_EIGHT: 104, NUMPAD_FIVE: 101, NUMPAD_FOUR: 100, NUMPAD_MINUS: 109, NUMPAD_MULTIPLY: 106, NUMPAD_NINE: 105, NUMPAD_ONE: 97, NUMPAD_PERIOD: 110, NUMPAD_PLUS: 107, NUMPAD_SEVEN: 103, NUMPAD_SIX: 102, NUMPAD_THREE: 99, NUMPAD_TWO: 98, NUMPAD_ZERO: 96, O: 79, ONE: 49, OPEN_SQUARE_BRACKET: 219, P: 80, PAGE_DOWN: 34, PAGE_UP: 33, PAUSE: 19, PLUS_SIGN: 43, PRINT_SCREEN: 44, Q: 81, QUESTION_MARK: 63, R: 82, RIGHT_ARROW: 39, S: 83, SCROLL_LOCK: 145, SEMICOLON: 186, SEVEN: 55, SHIFT: 16, SINGLE_QUOTE: 222, SIX: 54, SLASH: 191, SPACE: 32, T: 84, TAB: 9, THREE: 51, TILDE: 192, TWO: 50, U: 85, UP_ARROW: 38, V: 86, VOLUME_DOWN: 174, VOLUME_UP: 175, W: 87, X: 88, Y: 89, Z: 90, ZERO: 48 };

export type KeyNames = keyof typeof KEYS;

export type ModifierKey = 'altKey' | 'shiftKey' | 'ctrlKey' | 'metaKey';
export const MODIFIERS = ['altKey', 'shiftKey', 'ctrlKey', 'metaKey'];
/**
 * Checks whether a modifier key is pressed.
 * @param event Event to be checked.
 */
export function hasModifierKey(
  event: KeyboardEvent,
  ...modifiers: ModifierKey[]
): boolean {
  if (modifiers.length) {
    return modifiers.some(modifier => event[modifier]);
  }
  return event.altKey || event.shiftKey || event.ctrlKey || event.metaKey;
}

These files contain helpers we will use to make our service work properly. For example, keycodes.ts has a list of all the key codes, mapped to readable names, and modifiers has a helper function to check if one or more modifier keys are present in and event.

Theoretically, they would already make your life easier. You could use them as below.

window.addEventListener('keydown', (event: KeyboardEvent) => {
  const { D } = KEYS;
  if (
    hasKeycode(event, D) &&
    hasModifierKey(event, 'ctrlKey', 'altKey')
  ) {
    // Do action
  }
});

This code is much cleaner, but we can do better than that. What we want is a declarative way of listening to key events.

In the key bind service, you will create a new method called match(). We will have parameters so that you can specify the keys and modifiers you want to listen for, some extra options, and we will return an Observable that fires when the binding is matched.

public match(
  matchKey: KeyNames,
  matchModifiers: ModifierKey[] = [],
  options?: MatchConfig
): Observable<KeyboardEvent> {
  const { listenOn } = new MatchConfig(options);
  return new Observable((observer) => {
    const listener$ = fromEvent(listenOn, 'keydown');
  });
}

And a class for your extra config

export class MatchConfig {
  public listenOn: EventTarget = window;
  constructor(init: Partial<MatchConfig>) {
    Object.assign(this, init);
  }
}

Now that we have out plumbing in place, we will need to subscribe to our keydown listener and check if the current event's keys match the binding specified. To do that, we will use the methods defined in keycodes.ts and modifiers.ts.

public match(
  matchKey: KeyNames,
  matchModifiers: ModifierKey[] = [],
  options?: MatchConfig
): Observable<KeyboardEvent> {
  const { listenOn } = new MatchConfig(options);
  return new Observable((observer) => {
    const listener$ = fromEvent(listenOn, 'keydown');
    listener$.subscribe((event: KeyboardEvent) => {
      if (
        hasKeycode(event, KEYS[matchKey]) &&
        (!matchModifiers.length || hasModifierKey(event, ...matchModifiers))
      ) {
        observer.next(event);
      }
    });
  });
}

*note we added (!matchModifiers.length || hasModifierKey(event, ...matchModifiers) to the if statement so that it can match a binding that has no modifiers.

The service is now ready to be used. You can provide it to a component through the constructor.

constructor(private keybind: KeyBindService) {}

And to use it

const binding$ = this.keybind.match(KEYS.RIGHT_ARROW, ['ctrlKey']).subscribe(() => {
  alert('binding pressed');
});

// to stop listening to the binding call .unsubscribe on it
binding$.unsubscribe()

If you want to see this project in action, you can find it here.