How I contributed to Angular Components

In this post, I want to share my experience and lessons learned contributing to @angular/components and collaborating with the team at Google maintaining it. As an engineer at Infragistics, among other things, I am working for our IgniteUI for Angular components library where I am responsible for developing and maintaining IgxOverlayService. It allows rendering of an Angular component or an ElementRef overlaying other content in an app. Think dialogs, drop downs, tooltips and so on.

Several months ago I looked at Angular Components CDK (Component Dev Kit) — a set of tools that implement common interaction patterns whilst being un-opinionated about their presentation. It represents an abstraction of the core functionalities found in the Angular Material library, without any styling specific to Material Design. Think of the CDK as a blank state of well-tested functionality upon which you can develop your own bespoke components. One of the abstractions that it provides is an overlay service. This service has very similar functionality to the one I am responsible for in our product. Angular Components Overlay service also allows rendering of an Angular component or template overlaying other content in an app. This service looked like a good fit. Instead of implementing our own services I decided that we could use the ones provided by CDK. I started investigating if the CDK overlay is feature complete for our requirements.

Getting Started

I had a meeting with the management at Infragistics to discuss the possibility of switching from our IgxOverlayService to the Angular Components SDK Overlay. We decided that if we switched to the Angular overlay service we would have less code to maintain and we would be able to contribute to Angular Components open source project. Finally, the decision was made to try to switch to SDK Overlay. To make the switch happen developers at Infragistics were given the possibility to spend several hours a day contributing to Angular Components.

As a first step, I forked the repository, built the packages, ran the dev-app, and started looking at the contribution process and the standards that the Angular Components team follows. As soon as I felt more comfortable with the code I started looking at the issues in Material Components public repository on GitHub. If you want to contribute this is a nice first step to take along with helping with the documentation. Here’s a strategy for you to get started:

• Look at the issues.
• Grab one.
• Try to solve it.

The more issues you go through the more familiar you get with the code and the way components are developed and work. Before contributing it’s important to look at “Contributing to Angular Material” guidelines. They will help you avoid common pitfalls when getting started with open source.

New Features

After I went through several issues and started to feel comfortable with the library I took a look at the Overlay service and found that some specific features I needed were missing there. For example, the ability to render pure HTML elements, as well as allow the service to attach its final elements hierarchy at a particular place in the DOM. This is where I decided that I can suggest additional features to the Angular Components team and try to implement them myself.

Dictum factum. Together, with my team lead and product owner, we connected with the Angular Components team. After several emails we had a meeting with them to discuss the new features we needed in the overlay service. They were happy about our willingness to contribute to the product. They also explained the process of adding new features to the project. The most important was: do not break existing functionality. As they said, this library is used in many thousands of applications and all of them should work after a change is merged.

Design Documents

The first step in adding a new functionality is the creation of a design document. You can find the collection of all design documents of the Angular components team on their wiki page on GitHub. Before writing your design doc it is a good idea to check the existing ones and use the recommended template to start with. After checking the overlay design doc, as well as some more of the existing ones, I wrote a document for each feature I needed in the Angular Components Overlay. The process was hard and demanding for me, but rewarding in the end. Adding a new feature to the framework may look easy, but when you start to write the design document you find how hard it is. You have to see how the feature will work from all points of view as well as how it will integrate with the existing features. Writing all this in the document helped me to clarify my vision of the features I needed. For example, here are a few of the questions I had to answer:

• Is there another implementation out there to compare it with?
• How could the feature be implemented?
• What would the API be?

Once I finished the design documents, they had to go through a review by the Angular team. The Angular team was really fast and responsive. As soon as I had sent my design doc I had a review the very next day (your timing may vary). All the reviews I’ve got were concise, positive, and constructive. After addressing all the comments I got the green light to implement the features.

The first feature I focused on was the ability of an overlay to render a DOM element or an ElementRef. Fortunately, as soon as I completed the design document, and it was accepted by the Angular Components team, they told me this feature is already implemented and was included in a PR. I took a look at the PR and asked for some changes since some of the changes I needed were included in the PR.

Implementation

The second feature I actually developed was the functionality to close the overlay on an outside click. Imagine a modal dialog where one can click outside the dialog and this should close it. You can find the design document that explains the implementation details and the prior work here. With the design doc approved I start coding. It is not much different from fixing a bug. I implemented the feature and added the necessary tests. I tested in all supported environments. Pushed my changes and created a PR. Then members of the Angular Components team checked my PR and requested some changes. After all the requested changes were made the feature was added to the framework. My merged PR is available here.

The new feature helped the Angular Components team to solve some of the issues logged in the project. For example, MatMenu is using SDK’s overlay. When - user opens a menu it is shown with back drop and this makes the menu modal (issue 6927). As a result, users are not able to interact with the application items while the menu is open. Using the new detachOnOutsideClick feature helps to solve this issue. There are several other issues that could be solved with the help of this new functionality such as 9320; 15899 and 16036.

This story shares my experience as an Angular Component contributor. In the beginning it was intimidating. I wasn’t sure where to start and how everything worked together. However, if you start step by step: find the components you need, debug to figure out the flow of execution, and follow the contribution process then everything will come into place naturally. In the end I was really happy with my work. I learned a lot: the way Angular developers are using RxJS, how the tests in the framework are organized and more. Of course the feeling that you are contributing to a project used by tens of thousands of engineers is great. Also finding that the people responsible for the project are open to new ideas and very friendly. If you have some free time, go ahead, check the issues at Angular Components and fix one!