Forem: Zachary Levine

When should I use NgRx (or Redux)

Zachary Levine — Mon, 24 May 2021 02:54:21 +0000

When should I use NgRx or Redux?

"When should I use NgRx" is a question whose answers have changed several times over the years, and personally I find a lot of the guidance available online to be a little too "does it feel right" and “can something else handle what you are doing”. While informative and a great way to learn about some new libraries, this is largely not helpful for deciding when to say “yes, I would benefit from using NgRx for this project”. Over the last several years I’ve tried to come up with a mental framework for deciding whether or not a project would benefit from NgRx, and decided to share what I’ve come up with and see what others think.

Obviously this is subjective and I would love to hear what others have to say and see what the community would add or remove to this list!

Note that while this article references NgRx, this approach applies equally well to Redux in React for the most part.

The Conditions

In my experience, NgRx will prove to be a valuable addition to a project if…

There is enough information coming back from the server(s) that the frontend can effectively model state, and that the frontend has at least some non-trivial state beyond storing what the server(s) respond with.
There is a substantial amount of state that cannot be cleanly made the responsibility of some component. This includes the usage of component-specific Angular services.
State can be modeled with little-to-no ambiguity, without including detailed knowledge of which specific set of components are being rendered.

Let’s talk about each of these in greater depth.

There is enough information coming back from the server

This is largely to set a precondition that you should avoid trying to use NgRx in situations where the API is handling all or most of the state for the frontend. If your UI only needs to know about the { data, error, loading } states of API calls for the most part (like when using Apollo or rx-query), then chances are NgRx isn’t a great option.

This is due to how NgRx handles all state the same way regardless of source. Phrased differently, NgRx does not care if your state comes from an HTTP call, a complex set of multi-step user interactions, a simple form, or a multi-page complex form that can save partial progress. As such, NgRx is not a great tool for handling well defined state like that of an HTTP call since that is something so ubiquitous and well defined that it is almost always worth using a library that is specifically aware of API call state. The benefits of these tools are the simplicity they provide specifically because they are aware of the source of the data/state that they handle.

There is a substantial amount of state that cannot be cleanly made the responsibility of some component

Many popular frontend libraries these days are component based, and components are pretty good at handling state for their own little area of the HTML on a page. Further, many libraries supporting functionality like forms, modals, API calls and the like are quite good at managing the state of their respective features, often to the point where they make it trivial to handle state nearby to where it is actually being used.

Of course, sometimes this complexity still adds up to be way more than you want in a single component, and there might not be a good way to break that component up that you and your team are happy with. In these situations I personally reach first for component specific services, sometimes even multiple per feature of the app. This way the component can focus on the UI state, and act as a convenient mounting point for the logic (e.g. form validations, HTTP calls, anything else non-trivial) from use-case-specific services. This keeps everything “in the neighborhood” in which it is actually used, but still builds in a large amount of flexibility and abstraction.

State can be modeled with little-to-no ambiguity

This condition is perhaps the part I see mentioned the least in other articles and literature around NgRx, but to me is one of the most important parts of deciding if NgRx is right for your application.

This condition becomes hard to meet when an application cannot guarantee certain properties or behaviors are present and available in all situations. What if they are optional based on runtime parameters, but they are required in some situations? For example, consider a situation where, when one feature is turned on, then a second must also be present, but otherwise the second feature is optional; how do we define state for these two features? What does this mean for default/initial state? What happens in the components using these slices of state? Can you guarantee that the type definitions within a given reducer or selector will remain well defined and clear to read?

These are some hairy questions that always do have answers, but the answers frequently stray into the realm of “worse than the problems they were meant to solve”.

Not all apps can guarantee certain behaviors will always happen, or that they will happen the same way. For example, my current work projects are configurable, multi-tenant applications. This means we sometimes change which components are rendered or how they behave based on runtime conditions and feature flags (from a configuration object, plus the currently logged-in user’s particular data). The result is that it becomes difficult, at best, to keep in mind all possible interactions that will be available to the user, which data to retrieve and show, or which format that data will take when rendered. This gets even harder as the application evolves, and more “sometimes there, sometimes not” features are added to each page. This is compounded by the fact that a lot of these concerns that may have started out as global have now become specific to conditions in the UI itself (i.e. which components are rendered where and with what options), which pulls state back to our components (see condition #2).

The short version of this is, if there is a lot of flexibility in your app, it sometimes is best to choose the right component to render, and just let that component handle things for itself and it’s own children.

Conclusion

If your app meets all three conditions, I bet you will find NgRx (or Redux) to be a valuable addition to your frontend project. If it only meets one or two, I would personally be pretty reluctant, but there are exceptions to every rule (leave a comment with what exceptions you have experienced!)

One example of an exception I have seen is to the third point; large, configurable/dynamic forms. It might seem like being so dynamic might mean too much difficulty in defining state, but form controls virtually always have an exceptionally well defined interface. This sometimes creates situations where you can easily model state without knowing a single form control’s name/property ahead of time, as long as you know that it will always be a form control.

The Framework is not the Architecture

Zachary Levine — Fri, 17 May 2019 17:25:07 +0000

Frameworks are not architectures. However, at least in the frontend world Angular is somewhat frequently spoken of as if it were a full set of opinions, structures and design patterns. This is a mistake. What Angular does do is provide a set of tools so that you have the foundational pieces for as many different architectures as possible. But in no way, shape or form do these constitute an architecture on their own simply because these tools are bound together.

Put simply, an architecture involves definitions with regards to "how things will be done and organized" and how to define "things" and distinguish between them (among other things the definition might include). However, while that truthism sounds relatively straightforward, architectural decisions are anything but. The decisions are typically based on deeply technical factors centered around how categories of entities are defined and the design patterns that a team wants to use or avoid.

Going with this, "we use injected services" is not a statement of architectural significance for a variety of reasons, the largest being that there is no distinction about what logic does or does not belong in a service. To put this into the context of Angular, Angular services are on their own nothing more than a class that has a fancy way of being provided to your components at construction. You have as many design choices with Angular services as you can with anything else, be it Webpack provided singletons containing helper functions, Redux's reducers and actions, or pure Typescript. You also can easily make just as many mistakes. Nothing is stopping you from having non-change detectable state changes in your services, or from using HTTP interceptors in ways that hijack API request logic flow, or from abusing RxJs to create a single giant global state object that all components subscribe to and update directly.

"We use injected services…to manage state that is shared between components, and to handle business logic in a place outside of reusable/generic components" on the other hand is an architectural significant statement. It makes it clear that lines have been drawn (hopefully in greater detail than this) to help the team mentally separate out different pieces of functionality. It also helps suggest design patterns on how to make and keep those pieces separate. Another example would be using explicitly divided up groups of components, such as core UI/stateless components vs layout or use-case specific components as is common in a "presentational and container" components approach.

But the important thing to note is that this isn't something Angular created for you. These divisions do not exist within Angular, nor are they in any way inherent to it. Neither are these things an inherent part of React, Typescript, or RxJs. These libraries and packages are simply curated toolboxes (or an individual tool themselves) that have been put together with an eye towards promoting or avoiding various patterns, while leaving the door open as much as possible to whatever else is out there. And in any discussion of Angular it would be a mistake to not take note of the immensely valuable foundations for so many different architectures that Angular provides, and how it does so with such agnosticism. (It can also be argued that Angular entertains too many different approaches, but that is a different discussion)

Taking all of this a step forward, even if there were explicitly chosen best practices in Angular (or anything else) that clearly favored certain architectural choices (some contenders are RxJS backed reactive programming and "data down, actions up"), there is nothing forcing you to accept these choices. As long as you stay within the bounds of decent coding patterns and make informed decisions that do not conflict with each other, there is no reason why you cannot pick and choose as you want, or even forge an entirely new path.

But, be careful. Pick carefully what problems you can solve on your own, and maybe prefer existing patterns for things that have given you trouble in the past. Take into consideration the way things are currently being done and "the way the author(s) suggest", but don’t take it as gospel. There are many ways forward; your framework isn't the whole house, but it should always help you open doors to the ways forward that you can best envision and act upon.

BEM Best Practices

Zachary Levine — Tue, 15 May 2018 01:41:22 +0000

Over the course of several projects and team structures, I have tried a few different CSS naming and organization schemes, but in the end I have settled (so far!) on BEM. While there are many great articles that explain BEM’s basic principles and why they are helpful, I feel like they do not spend enough time discussing some of the practices that developers can use alongside BEM to help it truly shine. In this article I will introduce BEM but leave a lot of the introduction to the BEM website itself. From there, I will go through the set of mostly formalized practices that I and my current work team have come to love.

The benefits of BEM

First off, BEM has a great website for introducing people to the BEM method of CSS class naming, and I highly suggest it.

BEM is an approach to naming your CSS classes that I find provides fantastic semantic meaning and context given the resulting class names that appear in what might be otherwise plain and semantics-lacking HTML. When sticking (whenever possible) with CSS classes instead of other selectors, it provides a powerful organizational approach to your CSS by implicitly encouraging a one-to-one relationship between HTML elements and CSS classes.

What BEM is

It does the above by enforcing a naming scheme based on Blocks, Elements, and Modifiers (hence BEM). Going forward, anytime one of these words is used in the context of BEM it will be capitalized (e.g. "Block" instead of "block").

The "Block" is supposed to represent an entity in your HTML that can stand on its own. An example of such would be a particular HTML element containing child elements, or more explicitly the root HTML element of a component. Classes for Block elements are simply the name you give the block.

"Elements" are the child elements of a Block that have no real meaning outside of the Block they are contained within. CSS classes for Elements are named with the following format: Block__Element (note the double underscores). In other words, in a Block called "header" and an Element called "title" we would end up with header__title.

This is the core of BEM right there! Here is a small code example.

<div class=”header”>
  <span class=”header__title”>My Title</span>
</div>

As you can see just by looking at the class names, the div is the Block and the span is the Element. While the double underscores come across as ugly to some, their use provides instant recognition of what Block the span is related to. While HTML5 provides some semantic elements and components obviously have their own name as an identifier with semantic meaning, this adds a much richer selection of names as they allow the developer to create names with semantic meaning based on the context of what they are creating. This is not to say that you can just use BEM and avoid HTML5’s semantic tags - I strongly advise using them along with BEM for greater context (and better accessibility).

Before moving on, let’s discuss the Modifier. The Modifier is a class for when you need to override or, get this, modify the normal Block or Element’s CSS styles. They are signified with a double dash between the class they override and the Modifier’s name. A couple examples would be

user--current-user to change the appearance of a user card, such as when the user referenced is the current user
Or, navbar__navbar-item--current-route to highlight the user’s current route within a list of navbar items (e.g. navigation links).

Note the use of the single dash within navbar-item. There is no reason why you can’t use single dashes in each part of a BEM class name. The double dash and underscore are specifically to allow normal CSS class names such as navbar-item for each defined Block, Element or Modifier.

Some basic best practices

There are a few different approaches to BEM, but there are a few practices that are consistent across all of the ones I have seen, as follows. Note that they are not specific to BEM, but combined with BEM provide for a much more seamless and developer-friendly experience.

First, always try to use classes and not other selectors. Second, always keep to one BEM-named class per HTML element. The one exception to this rule is when applying Modifiers, as they are often applied alongside the unmodified class so that the Modifier only needs the overridden or added CSS rules, and no more.

These guidelines ensure, or at least encourage, a naming scheme (even outside of BEM) that will be easy to modify due to consistent and low specificity scores for your CSS classes, and provide a single class that impacts that HTML element. Here are two great articles about CSS specificity for the curious: from the MDN documentation and from Smashing Magazine.

The first point about maintaining low specificity scores means that overriding a class is as easy as adding an overriding class. If this low specificity were not the case, you would have to overcome the fact that while CSS classes only add a low score, the scores are additive. This becomes relevant when using approaches such as nesting your CSS, as that means that classes are combined when they are compiled (meaning, .x > .y becomes .x.y as a single selector). As specificity scores are additive, this means that instead of needing to be more specific than one CSS class, you now need to be more specific than however many levels deep the nested class you are overriding is at. This rapidly becomes unsustainable and painful to override.

The latter point about having a one-to-one mapping of HTML elements to CSS classes is that it results in a much simpler and cleaner styling section in your devtools display, and a single identifier to search your codebase for during development. Further, they make it much easier to identify unused CSS classes as a class that isn’t referred to in HTML is obviously not being used.

More BEM practices I have found useful

On top of all of this are some practices I have picked up and used across a variety of projects that have made this approach even better.

Nesting only for Modifiers. CSS class nesting can be a nice way to avoid rewriting CSS, and while not required for Modifiers to work as expected, it makes for nicer reading to many. It also simply makes sense as Modifiers by their very nature override existing CSS, which is what happens to the more specific nested classes when nesting. Nesting Modifiers also means that they automatically result in The Right CSS, taking what the modified class set and overriding only the necessary values. When using this pattern, you can apply only the Modifier class instead of both it and the overridden class.

However as suggested by the “only”, I highly recommend not nesting Block__Element classes nested underneath their respective Block class. While this can look nice, it means that every Element class will be overriding the Block class’ CSS. This means that any CSS rules the Element class doesn’t care about must also be overridden. This requires that the developer write extra (read as: excess) CSS for overriding what might be app or user agent defaults that the Block set with different values. In my experience this often causes difficulty in refactors or feature changes as the Element class does not come with the expected or globally set defaults. This tends to cause the class to become unnecessarily bloated, and prevents a simple copy-paste of the class when refactoring as these excess CSS rules are not desired in many cases.

Another thing that I do not believe I have seen any articles mention is that your Blocks can be “scoped”! In other words, you can have a Block at the root HTML element of your component, and “declare” a new BEM Block for some child group of HTML elements. I find this greatly increases the semantic value of my BEM classes. The basic principle here is that Block classes declare a new scope within your current BEM context, just like how scope works in Javascript.

I personally do this scoping by taking the Element name from the “BEM scope”(™) I am currently working within and using that (or something with similar meaning) as the new BEM Block scope’s name. Depending on the context I will use the parent scope’s Element with some variation that adds semantic meaning in that context. One way I do this is by taking the Block and Element and hyphenating them to create the new Block. An example of this would be header and header__article becoming header-article as the new Block. This is nice when it isn’t worth it or meaningful to create a new, separate component.

Here is an example on Codepen.io with a “header” and some articles, showing BEM scoping at work. A quick note, in most situations “articles” would obviously be their own component. I am doing it this way here just to present the idea.

Lastly, I address CSS rules that are commonly used together by using “extends”, a feature most CSS pre- and post-processors provide. I use this as it allows a simple importing of a file containing shared classes (which are named with straightforward, non-BEM named styles) and extending the relevant class from that file in the BEM named class that needs those values.

This makes it easy to adhere to the previously mentioned guidelines, such as one class per HTML element, except for Modifiers. This happens while also allowing a simple and composable collection of commonly available utility classes. This works especially well for keeping things visually consistent, such as different input tags used in different components.

Hope this was helpful, and always, suggestions on alternatives or better approaches and practices are appreciated!

Mistakes in CSS

Zachary Levine — Wed, 04 Apr 2018 02:52:26 +0000

Recently I came across the CSS Working Group’s “Incomplete List of Mistakes in the Design of CSS”, a post about items in the CSS standard that are now viewed as mistakes. While not a new article, I had never come across it until quite recently. I immediately found it fascinating, in large part due to how I have come across a few of these issues, and in several cases I didn’t even realize it.

I figured I would discuss some of the “mistakes” that caught my attention or have been particularly vexing for me in the past.

white-space: nowrap should be white-space: no-wrap

and line wrapping behavior should not have been added to white-space

The first thing in the list is an easy one. Why (why!?) “white-space: nowrap” is involved in line wrapping, I never understood. “Whitespace” feels semantically irrelevant to the goal of causing things that are not whitespace to wrap. This weirdness has caused me to have to google the syntax for this nearly every time it came up for me.

Vertical-align: middle should be text-middle or x-middle because it's not really in the middle, and such a name would better describes what it does

This was something I never realized until I saw this. This seems like an immediate, likely culprit for why vertically centering text always seemed to require something like vertical-align and padding to get it just right. Could have also been a mistake on my part, but this doesn’t sound like it helped.

Percentage heights should be calculated against fill-available rather than being undefined in auto situations

If I understand this entry correctly, this issue was especially problematic to me on one occasion. This was especially irritating as it was in a way that was effectively unfixable using just CSS as far as I could tell. (If you have a solution, please comment! I could easily have missed something about this situation). The problem was a sidebar with a header that grew, and a scrollable section beneath. Further complicating this was that the sidebar was below an existing header, and the results for responsive behavior precluded using vh values. The result was that the percentage height was always undefined, and the scrollable section would not be, well, scrollable. As such, we were forced to give the sidebar header a static height in order to make the “content” section of the sidebar scrollable/give it a defined percentage height value. Everything we tried came back to lacking a defined height value to give to the scrollable div.

The top and bottom margins of a box should never have been allowed to collapse together automatically as this is the root of all margin-collapsing evil

It doesn't show in markdown, but "the root of all margin-collapsing evil" is how it appears normally. I didn’t add the emphasis. That is the only thing bolded in the original post. I think it speaks for itself.

Tables (and other non-blocks, e.g. flex containers) should form pseudo-stacking contexts

I don’t use tables often myself, however I have seen some issues with tables, especially with accessibility (for example link). I can see making a new context for display being worthwhile.

'overflow: scroll' should introduce a stacking context

I was not aware of this one, and am not aware of any problems this might have caused me, but this sounds gross. While stacking contexts are typically not a problem, when they do become a problem it is often frustrating. I can imagine this causing more of a problem than a developer was likely bargaining for given the details involved with stacking contexts with fullscreened elements that are also scrollable.

A lot of other issues regard semantics and a lack of vision for future use. The former is obviously a problem, whether it be a change in the ordering of arguments (e.g. height vs width) or in wording (“border-radius only affecting the corners). The latter is more a usage issue that can hopefully be fixed with backwards compatibility in a future version.

Hopefully this brings attention to issues you have had in the past and maybe gives some thoughts as to some solutions!

Returning To AngularJS (After Angular 2+)

Zachary Levine — Tue, 27 Mar 2018 00:43:44 +0000

There is a lot of discussion about going from AngularJS (Ng1) to Angular 2+ (NgX), however there is much less discussion about what to expect when going from NgX to Ng1. I made that technology change twice now between a few job and project switches I made in the last couple years. In this process I realized that I had taken many of the differences between the two for granted.

I decided I’d write about what differences in particular caught me off guard, since more and more teams are leaving AngularJS. While this sounds counterintuitive, I imagine many engineers are in my position of leaving Ng1 at some point in their career, and then returning to it after joining a new team or project like I did. Many of these projects still need developers with Ng1 experience to maintain legacy code or write new Ng1 products. Sometimes this happens just a couple months after their last Ng1 experience, but could also be far longer since their last exposure.

I will not be focusing on the technical details of Ng1 and its NgX successor, and will instead focus on the different developer experiences. Obviously there will be some technical detail thrown in.

I got into front end development using Ng1, and while I never fell in love with Ng1 I definitely became fond of the framework. It provided what I needed, and a simple enough learning curve to write clean and reusable code. I worked with it for a while and learned what parts to avoid and which worked better, for my own coding style and my team’s. I avoided things like using separate controllers for every directive in favor of linking things directly to the directive much of the time. I relied heavily on other aspects of the framework like the dependency injection and automatic change detection.

Then I switched projects and was using NgX, which, outside of observables, was an even simpler learning curve than Ng1 had been. Part of this was obviously due to my previous experience with Ng1, which does have some basic similarities. But observables in particular posed some challenge at first, primarily due to a misunderstanding I had about the difference between the observable sequence of execution and the observer of that sequence. But outside of that brief hiccup, NgX was beautiful. Components felt more than just self contained, but truly sovereign and in control of their own existence. The much better typed dependency injection system meant I could more readily avoid “props drilling”. This is when a value is passed down through through many components, a common problem I had with Ng1’s directive hierarchies. Things in NgX just felt...natural.

It felt natural to use values as plain Javascript/TypeScript without any framework-added properties to my objects like $$hashKey, and to act on lists of events using observables. Working with that new typed dynamic dependency injection system was a lot of fun as well. All of this powered by RxJs observables, TypeScript, and a much more focused, opinionated framework made for a fantastic developer experience.

Then I moved back to Ng1.

To be honest, in the year or so I had become familiar with NgX I had forgotten about how often I was using asynchronous behavior. I had forgotten that Ng1 uses $$hashKey to track values for change detection during its digest cycle. I had forgotten why immutability had become so prominent a pattern in my coding patterns with NgX.

These issues came up in ways that, while an important (re)learning experience, were painful and felt unnecessary to still be dealing with on my return to Ng1. Ng1’s use of the $$hashKey property meant that whenever an object was created within Ng1’s context, I had to take care and remember what it was doing. I could no longer use Object.assign() or the spread operator to create new objects based on existing ones and call them immutable, as the $$hashKey property would be included unless explicitly handled or removed. Ng1 would still be tracking the object and updating it during the digest cycle. This played hell with my usage of Redux with Ng1 as it would cause unexpected and unwanted synchronization of changes.

More embarrassingly, issues implementing asynchronous behavior came up when I took for granted the safety zone.js provides in NgX. Namely, that zone.js guarantees that asynchronous code will only run once the function that made the async call completes, ensuring the expected execution path. While a great feature in NgX, I had not been thinking about this when I returned to Ng1 and wrote functions that would not complete due to calling an asynchronous function in the middle, as it would hijack my expected sequence of execution. I had remembered to handle async behavior properly in my React development experience, but had forgotten about this crucial difference in how async activities are handled between Ng1 and NgX.

My issues continued as I overused scope events. This is something I had specifically avoided doing during my first stint as an Ng1 developer. In NgX I had found it so easy to simply subscribe to an observable whenever I needed to react to events, but with Ng1 I then found it far harder to scale this approach with scope events. The result was convoluted and hard to debug as scope events work across an excessively broad area of the component hierarchy. Greatly exacerbating the issue, scope events are not provided to the directive or component using them, but can be emitted or acted upon from almost anywhere. In NgX observables are largely provided to the client component either as an input (e.g. EventEmitters) or via an injected dependency like a service.

All in all it was definitely a valuable set of lessons for me. In patience, remembering old practices and patterns, and in needing to spend more time re-familiarizing myself with my old tool set before proceeding. Hopefully this article highlights some issues that others may run into so that their immersion back into Ng1 goes more smoothly than the first month or so that mine did.

Share your own experiences relearning a technology in the comments!

Improving The Use Of Constants

Zachary Levine — Wed, 14 Mar 2018 17:52:21 +0000

One thing that has always been a great pattern in software is constants. I’ve always had a “love it then hate it then love it then…” relationship with constants. They felt helpful, but I felt like they weren’t doing as much as, or quite exactly, what I wanted. There is a better way indeed! It wasn’t until I started rereading “Structure and Interpretation of Computer Programs” from MIT Press (a great read) that I realized this. That way is to not just get the constant value as an export from a file, but also do checks against it with a method, typically provided from the same file.

Before detailing the difference in pattern, let’s first introduce the problem.

Why constants at all?

We will discuss two common problems I have seen that constants are used to solve. Namely, to implement a sort of pseudo-typing, and to replace magic values such as strings or numbers. In this article we will focus on magic strings, as I have found them particularly common and annoying. Magic strings are what many call the usage of an explicit string value used in code, such as state.view === ‘some-view’ (the same applies to all situations, such as props.view, $scope.view, etc).

While this is pretty explicit, this is not really reusable. If the property on state changes name, every instance where that check happens must change. Likewise, if we decide that ‘some-view’ is not a good name, every check must change.

This is why we use constants in these situations. If we have an object called “views” and give it properties for each value, the string value for each property can be changed without needing to change the actual checks. I personally have found this to be very useful for defining the constants for a lot of my view configuration and states, such as if ( view === editing ) {}, or if ( user.type === teacher ) {} (as opposed to user.type === student).

Why this is still not enough

This is not quite great, as if the property name whose value we are checking against the constant changes, or the constant variable name changes, we still need to change every place where this condition appears. However we have decreased the rate at which we must make changes as the constant itself is now a variable we can refer to. In other words, we no longer have to change every check if “teacher” becomes “educator”.

This is nice! We have eliminated one of the two sources of issues by creating an abstraction over the values themselves. We have also done so in a way that allows us to define a single location where all constants of this kind exist. This makes it easier to figure out what options already exist and were intended to exist by the developer.

How we can vastly improve constants

We can add another layer of abstraction by adding methods that do the checks for us, and in the process make our code cleaner and easier to work with and look at while adding very little overhead. This may seem obvious to many but the idea of doing this slipped my mind for a long time, so hopefully this will remind some people and teach others about this simple technique.

Put as simply as possible, use constants, but never openly. You should define constants, explicitly (preferably as properties of an “enum” object, like what TypeScript provides), but also write methods that do the actual check for you.

These methods should do nothing other than determine if the value given is equivalent to a particular constant’s value. It should not know about or consider any other properties of a given object other than what is necessary to do the check. This keeps the method simple and able to be used in any case where this constant might be used regardless of the object being compared. It also means we can export this method as a normal ES6 method from a file. This is superior to doing “open” (as in, in the code where the constant is used visibly) because we never have to know if there even is a constant, nor anything about the particular argument we are checking the constant against.

To view a simple example of without constants, with open constants, and with abstracted constants, checkout the contents of this gist.

With this approach, we can change the name of the property we are checking, the constant’s name, or the value of the constant separately without changing anything else.

This will work for any level of check, as there is no reason we cannot expand the complexity of this to involve multiple property checks against an object instead of a primitive string value. The important thing here is the abstraction used.

Happy abstracting!

CSS Stacking Contexts for Fun and Profit

Zachary Levine — Tue, 06 Mar 2018 03:02:24 +0000

At work recently I came across a situation where we fullscreened an element within the DOM using the browser’s native fullscreen API. This is normally trivial, but this situation was a bit weird as the element we were fullscreening provided a map of a basketball court, with locations from which shots were made laid on top. When the user clicked one of these shot markers, we opened a modal on top that showed the details of the play as it happened and the relevant video footage.

When the shot map was not fullscreened, this worked fine, but when we opened the modal, we suddenly had a conflict between the stacking contexts (layout and display ordering) for the rendered DOM tree and the z-index for the modal.

I’ll spare you the product details, but the problem is that fullscreened items modify the browser’s stacking context. The result was that even though we added the modal as the first child element of the < body > tag, it did not matter what z-index we set for it, it would not show. It would always be hidden behind the fullscreened shot map, making it appear as if clicking the shot marker on the map suddenly had no effect. Even worse, this allowed the user to spawn multiple modals as they could now continue clicking the normally hidden shot markers.

This last problem was easily solved by only allowing one modal to be open at a time, but that (single) modal was still hidden, and so another solution was needed.

The root issue here is that even though the modal was at a higher level in the DOM than the shot map, the use of the fullscreen API created a new stacking context, and this stacking context took precedence over normal z-index usage. The modal still existed and was rendered, but invisibly, underneath the new stacking context.

The reasoning for this is that the stacking context added by using the fullscreen API creates a new context, which is added to the tree as the last item in the tree. CSS creates a painting order (which is an ordered set) that results from the stacking context, which is a tree. It does this using a post-order depth first traversal of the stacking context. I won’t go into what that means here (but you can read about CSS using it and the traversal, which I highly suggest), but put simply whatever is added to the tree (or appears in the tree) later according to this traversal will appear closer to the end of the ordered set (the painting order). This matters because CSS prioritizes items in the ordered set based on how close they are to the end, as it renders things in order. Appearing later means it is painted later, and more likely to appear “above” other elements.

As the stacking context for fullscreened items is added after properties like z-index, this results in a fullscreened element taking precedence. This makes sense given the purpose of the fullscreen API, but this is what de-prioritized our modals out of visibility.

Fortunately, there was an easy, non-hackish way to fix this. The solution takes advantage of the fact that while setting an element as fullscreen modifies the stacking order, sibling items to the fullscreened element follow the normal usage of z-index. This can be a little more complicated than it sounds as elements that need to be visible alongside/above the fullscreened element must be re-appended to the parent element of the fullscreened element. For our case this was not an issue as we were already appending the modal to the tree on the relevant actions after the fact, and could simply change where we appended the modal. In other situations, you would have to do this deliberately.

I am still learning how to best make use of stacking contexts, so apologies if anything is incorrect. One thing I really enjoyed about this problem was that it was not an issue with the libraries we were using or a normal Javascript problem, but a data structure one! Nice little break from the normal sort of problems we encounter.

Dependency Injected Style Overrides For Angular 2+

Zachary Levine — Mon, 29 Jan 2018 17:49:22 +0000

The one thing I didn’t like about Angular 2+....styling overrides

Angular 2+ is great. In its current form it is a powerful set of tools that runs quickly, is easy to use, and provides some fantastic abilities right out of the box. But there is one place I have always found myself frustrated with Angular 2+, and that is in how, contrary to pretty much everything else about it, styles felt painful to override.

The “standard” options have typically consisted of abusing ng-class, something that is much more suited to changing CSS classes at runtime rather than CSS classes that override the defaults of an existing component. Plus then you have to set a condition to use ng-class with, such as an input to the component that ng-class can be used with to set the right set of overrides.

But you can also interpolate the string values, i.e. “ class=”” “. This still requires an input of some sort to figure out what to get, be it an object full of strings passed to the component, or an input to use like ng-class above that the component can pass to a provided service that can then return the appropriate strings to get the object.

Both of these are gross. In both cases we must add yet-another-dependency to our component that it must take regardless of whether or not we are overriding anything, and both are slower than determining classes at compile time, given the classes will change when ng-class runs (leading to possible flash of improperly styled content) or the service returns new strings.

We need a solution that does not require us to provide any more inputs than are necessary, and makes the overriding classes available when the component compiles so that the component compiles with the correct styling.

A solution exists!

We can do this with a single injected dependency, and with configuration instead of code!

I’ll explain first, then walk through the live example.

You can provide objects as values. These can be simple, JSON-like objects, made available with simple “export const …….”. Simply interpolate the strings made available in the object (if no value is provided, it still works, without throwing any errors!) and….you are done. The objects are merely configuration JSON practically speaking, and are provided with a single line of dependency configuration wherever in your component hierarchy you want the overrides to apply.

The only other requirement is that the relevant CSS classes are made available, but by simply making the overriding CSS to available to the component (through the normal array of styles files to draw from) we don’t have to sacrifice usage of the Shadow DOM or its polyfills. In other words, the usage of CSS is exactly as one would expect for a normal Angular component.

This solution does not allow for the possibility of a flash of improperly styled content as Angular renders after dependencies are provided, at which point the CSS classes to be interpolated are already provided. We do not need to provide every override as nonexistent properties will not return anything, and no override is applied.

What it looks like

So, let’s walk through the example, seen here on Stackblitz.

If you check out the my-button.component.ts file you can see that we specify no providers, but instead specify an @Injector for “Values” in the constructor function on line 14. This is all we need to inject the styles override object!

You can also see that we define a list of styles files to draw from on line 6, that includes the normal my-button.styles.css file, as well as two overrides files. This simply gives us access to both the default styles and the overrides. Pretty normal stuff for any Angular component.

In the app.module.ts file we see that we import a “Default” object (on line 23) that imports a default object to provide. This object contains….nothing! We don’t need to override the default, so this can just be an empty object. If we wanted, we could have the default CSS classes defined here instead of the my-button.component.html file, but this is the approach I am using.

I use the same providers line in the components (First overriding component, Second overriding component; see the “providers” property for the components on line 9 of both) that override the styles as in app.module, but using their respective overriding objects (First override, Second override).

And that is it. Nothing else is necessary other than defining CSS rules for your overriding CSS classes that you are overriding with.

In conclusion, we have a fast, configurable option that requires minimum modification to existing code that allows us to override existing styles to normal, vanilla Angular components. No hacky weirdness, no abuse of ill-suited tools, and no conditionals.

Some opinions to be aware of in the example

CSS file organization

I chose to put the CSS classes for overriding in different files to express the fact that they are not part of the normal styling for the component. You can put the CSS class definitions wherever you want.

The Default CSS object

While you could put the default CSS classes to apply in the default object, I prefer to put them in in the HTML. This requires that the CSS used follows a system that is easy to override, as well as the fact that named CSS classes provide fantastic semantic context to HTML. It does require usage of an approach to CSS that emphasizes low specificity values so as to easily override the existing classes - I suggest BEM for this in the next section for this reason. This also makes it easy to use the same default configuration object for all components.

Usage suggestions

Combined “super” configuration objects

This was a simple example, but in more realistic situations you probably will not want to be handling configuration objects for every configurable component that exists. I still suggest creating a configuration object for each component, but instead of providing them individually, provide a larger “super config” object. This object can be created (and then provided via dependency injection) with a simple function that returns an object that contains all the key-value pairs defined in each object it is given. This can be used exactly like in the example since the keys for the object will exist as expected, and everything else will be ignored.

Don’t overuse it

You probably should not use this excessively. It will most likely work best when there are only 1-3 non-default configurations the component can be in, such as when a certain type of user should have the given element appear in a specific way to them.

Exceptions to this “rule” exist though, such as icons. You could have overrides of this sort defined for every possible icon you want to use a given component for. If those components need a click handler that can easily be provided as a click handling attribute directive by the parent. This is obviously a matter of your particular use case.

Keep CSS easy to override

Another thing is that this works best with a CSS class scheme that encourages a 1-to-1 relationship of CSS classes to HTML elements. In the example I use the BEM approach that I typically favor, but any approach that results in one CSS class for one HTML element will work. This is due to the fact that it is easiest to override an already applied CSS class if you only need….one other CSS class. CSS specificity rules mean this is easiest if there is only a single CSS class that relates to the targeted HTML element, as multiple classes immediately creates complications with regards to specificity.

You can use this approach in React!

Since React components are simply JS objects with added functionality, you can provide the configuration objects via React’s Context API, which provides similar hierarchical dependency injection functionality to what we used here in Angular 2+. Simply append whatever strings are returned by the override to what you provide className.

Enjoy!