DEV Community: Manuel Micu

Avoiding CSS style collisions when building a UI widget

Manuel Micu — Fri, 01 Jul 2022 01:06:15 +0000

Use case: you're tasked with developing a UI widget, that can be used in any integrator webpage.

Classical examples: Google Maps, chat widget.

Problem: some integrators have conflicting requirements:

Make sure there is no style collision between the integrator-specific style and your widget style
Allow the widget to be customised with integrator-specific custom style

The bad approach

First, let's start with the simple, but very risky approach. You can have the widget and the integrator style side-by-side, without anything in place to create any isolation, and hope it will work. However, in reality, there can be a wide variety of CSS style conflicts.

Examples:

CSS selectors of the integrator can have higher selectivity than the ones used in the widget (example: #root .button > .button)
common CSS selectors (such as .root, .button) might be used by both the integrator and the widget code, without being aware of each-other
global style can pollute elements in either direction (example: * selector used in the widget or integrator styles)
wide-impact element selectors (example: div, img)
!important (used by the integrator own source code, or part of some third party library outside their control)

To accommodate the 2 requirements of style isolation AND customisation options, here are a few aspects to consider.

Style isolation level

Technical solution available:

side-by-side integrator/widget code. A few CSS tricks will be needed to avoid unwanted style conflicts. This approach will be looked into closer bellow.
iframe
shadow DOM

Style customisation level

This is actually a range, that can go from:

Little to no customisation
Specific allowed customisation
Anything can be customised.

Technical solutions available for allowing style customisation:

shared CSS (when side-by-side integrator/widget)
definition of CSS variables
style passed to the widget, as a configuration, or a file:
- passed in-process at initialisation
- passed using iframe postMessage
- passed via HTTP retrieval, based on a unique integrator id
complete customisation, by allowing the integrator to fork your widget source code (if your widget is open source)

Conclusion: Depending on your needs and choice, the best solution will not be the same for everyone.

Let's see a few of these approaches in more detail in the next sections.

NOTE: There is a code sandbox at the end.

Approach 1: wrap your widget with an `iframe`

This solution is very effective, since it creates a new context. CSS style outside the iframe will not influence your widget.

You then have many options to define your customisation interface, while keeping the rest of the widget style immune to style collisions.

Important remark: there are 2 ways to add an iframe to your widget:

add it yourself, inside the widget code. This applies it to all the integrators.
tell the integrators to add the iframe around the widget. This way, the integrator creates an isolation between their style, and the widget style. They can then apply custom CSS, the same way as the side-by-side approach:

<div class="widgetWrapperToOverrideWidgetStyle">
  <div class="widgetRoot">Injected widget</div>
</div>

This approach is one of the preferred ones when you want to avoid style collisions at all cost.

Approach 2: Side-by-side integrator/widget, with `CSS unset` isolation

This solution may be enough in many cases. But it comes with some drawbacks to the widget:

it resets the browser defaults (example a div will no longer have display: block, but display: inline). So extra style is required to restore that. In theory, many properties may be impacted. In my experience, setting display: block is enough.
some unintended style override is still possible. This happens if high selectivity CSS is used on the integrator side, such as !important.

However, this last point is also an advantage, since it allows the integrator to customise anything, if needed.

Useful CSS concepts related to this approach:

In order to make this work well, you need to be careful not to pollute the style of the integrator elements. This can be avoided with discipline in the kind of CSS the widget uses.

What you need to avoid:

* selector
element selectors (examples: div, h1)
selectors with low specificity, using common names (example: .button).

All these can be made safe by using them within a higher selectivity selector, such as: #widgetRoot *, #widgetRoot div, #widgetRoot .button.

Extract of the implementation of this approach:

/* this is the main trick */
.widgetRoot * {
  all: unset;
}

/* Compensate unwanted effect of `unset` */
.widgetRoot,
.widgetRoot * {
  margin: 0;
  padding: 0;
  border: 0;
}
.widgetRoot div,
.widgetRoot h1 {
  display: block;
}

With the CSS trick described above, you now have more isolation between the integrator style and the widget style. Integrator style should not, by default, have unexpected impact on the widget style.

It is still possible to customise the widget style, but it requires deliberate intention, since it requires high selectivity (for instance use of id selector). Example:

#integratorRoot .widgetRoot {
  --color-theme: pink;
}

Depending on the selector approach used inside your widget, there are 2 scenarios:

stable widget selectors (example .widgetTitle, .widgetFooter). This does allow the integrator to reliably override the style of these elements.
unstable widget selectors (example: generated with file content hash, .rDhk_jr_i8). This can be done on purpose, to signal the integrator that they should not attempt to customise other things other than the customisation interface that you defined, such as your CSS variables).

In conclusion, this solution making use of all: unset may work well in some cases. But because of its soft type of boundary, you may still encounter some issues with accidental CSS style overrides. And, you will need to write more CSS to compensate for the unset effect, and avoid CSS conflicts.

So if you want to play safe, then harder isolation context approaches are probably preferable.

Approach 3: Shadow DOM

I don't have experience with this approach, and I didn't look into it at this point[time constraint]. However, the described use-case is probably well-suited for what shadow DOM has to offer (style encapsulation).

I will leave it to you to read more about it: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM

Code demo

I implemented a quick demonstration for Approach 1 and 2 side-by-side. Feel free to explore the code.

Disclaimers:

The shared demo does not contain production-quality code.
The approaches that are listed here don't represent an exhaustive list of all possible approaches. Feel free to suggest others that I missed.

Visualization of route navigation in a React app

Manuel Micu — Sun, 19 Sep 2021 23:00:59 +0000

This post describes how you can build your own visualization of the navigation inside a React web application.

Such visualization can transform a complex user journey into a more easy to understand, interactive network graph.

Context in my company

Tech stack:

react SPA
react-router
30+ screens
screens grouped in multiple bundles, loaded only when/if needed
folder structure: src/screens/<bundle>/<screen>

Problem

No single place to view all these routes, that would allow new developers to quickly understand:

how the screens are split into bundles
the available navigation pathways between these screens

The alternatives would have been to:

Look inside the collaborative design tool. However there was no representation of ALL the screens, but rather they were spread in multiple places, usually grouped by feature.
Look inside the codebase, and follow the code. But this would be too tedious if you just want an overview of ALL the screens.

Solution

This started as a side project that I played with in a few evenings, since I wasn't sure if the end result would look good, or if my colleagues would find it useful.

The idea was simple: run a script that would generate a network graph made of:

nodes [{ id, bundle }] - screens, grouped by their bundle
edges [{ from, to }] - directed arrows between the screens, indicating that the navigation between these 2 screens is possible.

These nodes and edges would be generated by looking through the codebase, with an algorithm described by the following pseudocode:



nodes = [];
edges = [];
bundles = findBundles(); // find all the src/screens/<bundle>
bundles.forEach(bundle => {
  screens = findScreens(); // find all the src/screens/bundle/<screen>
  screens.forEach(screen => {
    nodes.push({ id: screen, bundle  });
    paths = findDestinationPaths(); // regexp of PATH.[...] inside src/screens/bundle/screen
    paths.forEach(path => {
      edges.push({ from: screen, to: mapPathToScreen(path) });
  });
});

This script will output 2 files: nodes.js and edges.js. These files were added to .gitignore.

Drawing the graph

I used vis.js network library (link) for drawing the network graph.

This library comes with a few useful built-in features, out of which I used:

left-to-right hierarchical layout
color grouping, based on the bundle
physics engine, using repulsion solver

NOTE: I had to play around with some of the options, in order to find the ones that gave the best looking output.

Running the script

I added a new script entry inside package.json, that does:



"view-network": "node scripts/network/extract.js && http-sever scripts/network/index.html

The index.html file will do a few things:

import the generated nodes.js and edges.js
import the drawing library
draw the graph
add extra UI features, such as a dropdown select menu, so that you can choose which bundles to view.

Result

Here are 2 examples of graphs that can be generated:

NOTE: I had to add some blur, so that I don't share confidential details.

Another example, using a different layout:

Conclusion

Sometimes your side-projects can turn out to be useful for your company.

The essence of The Pragmatic Programmer

Manuel Micu — Sun, 15 Aug 2021 20:09:32 +0000

I recently read the book "The Pragmatic Programmer" and I'd like to share two lessons, which best capture the essence of the book.

1. Our job is to help people understand what [requirements] they want.

Getting the requirements definition right is one of the most difficult part of the job.

The initial requirements are just a suggestion, an invitation to explore all the options, and ask all the relevant questions that will help create refined requirements.

Don't expect your product manager to give you the ready-to-code requirements. Do your job and help them understand what they want.

Also don't get frustrated in the process. It is normal to require a few feedback loops.

When you step-up and fulfill this part of the job, your company will value you more (and may give you a raise), and you will enjoy your work more.

2. Our job is not just "software developer". It's "problem solver".

Writing code is a just one of the tools for solving a problem.

Sometimes writing code may be the wrong solution, and would only create more problems.

Other times, your code may just solve a symptom, but not the root cause of the problem.

When you start seeing yourself as a problem solver, you start looking for solutions in all possible places. Not in the code that you usually write, but also in:

a simple unix command (rather than your usual programming language)
requirements that need to be further clarified,
design that needs to be simplified,
documentation that needs to be created.

You are not restricted to just writing code to address the problems that you are faced with.

Once you realize this, and you take it upon yourself* (defined as: to accept responsibility for something without being asked to) to solve such problems, then you will be a step closer to become a Pragmatic Programmer.

How to write clean functions

Manuel Micu — Wed, 03 Jun 2020 19:10:34 +0000

The following ideas are inspired by the book Clean Code by Robert C. Martin.

Introduction

This tutorial will demonstrate a set of basic principles that will help you write cleaner functions, that is, easy to read and easy to update.

Most coding articles usually focus on the latest hot topics. There are not many articles about simple and sometimes undervalued ideas, like how to write clean code and clean functions.

In this tutorial, you will practice writing clean functions, starting from an initial code sample, and improving it step by step using the following principles:

Small
Do one thing
One level of abstraction
Less arguments the better
No side effects

These principles are relevant for any programming language, however the code samples will use JavaScript.

Prerequisites

Basic knowledge of JavaScript.

Step 0 — Starting code

You will start with the following code sample, which does not satisfy any of the principles of clean functions:

const getProductPrice = async (product, isSaleActive, coupon) => {
  let price;

  try {
    price = await getPrice(product);
    product.userCheckedPrice = true;
  } catch (err) {
    return { result: null, error: err };
  }

  if (coupon && coupon.unused && coupon.type === product.type) {
    price *= 0.5;
  } else if (isSaleActive) {
    price *= 0.8;
  }

  return { result: Math.round(price * 100) / 100, error: null };
};

Step 1 — Small

Making an effort to keep your functions small, ideally between 1–5 lines, is the easiest way to make a function cleaner. Keeping this principle in mind will force you to reduce your function to its bare minimum.

Go ahead, try to refactor this functions on your own first, then come back here and compare with the solution proposed bellow.

We can make the main getProductPrice function smaller by simply extracting some of its functionality into another getPriceWithCouponOrSale function.

const getPriceWithCouponOrSale = (price, product, isSaleActive, coupon) => {
  if (coupon && coupon.unused && coupon.type === product.type) {
    return price * 0.5;
  }
  if (isSaleActive) {
    return price * 0.8;
  }
  return price;
}

const getProductPrice = async (product, isSaleActive, coupon) => {
  let price;

  try {
    price = await getPrice(product);
    product.userCheckedPrice = true;
  } catch (err) {
    return { result: null, error: err };
  }

  const price = getPriceWithCouponOrSale(price, product, isSaleActive, coupon);

  return { result: Math.round(price * 100) / 100, error: null };
};

Step 2 — Do one thing

In the starting code sample, the function getProductPrice does many things, all contained in the body of the function:

it gets the original price
it updates a product boolean
it handles the error
it applies a coupon or a sale
it rounds the result

In order to make a function do less things, you have 2 options:

move functionality one level down, by extracting a separate specialized function, like you did in step 1 with getPriceWithCouponOrSale function.
or move functionality one level up, at the caller level. By applying this approach, we could move the error handling out, and have a getProductPrice function focused on one thing: getting the product price.

const getProductPrice = async (product, isSaleActive, coupon) => {
  const originalPrice = await getPrice(product);
  product.userCheckedPrice = true;
  const actualPrice = getPriceWithCouponOrSale(originalPrice, product, isSaleActive, coupon);
  return Math.round(actualPrice * 100);
};

For simplicity, the error handling on the caller level, is not reproduced.

Step 3 — One level of abstraction

This is something often overlooked, but it can make a major difference in achieving a clean, readable function. Mixing levels of abstraction inside a function is always confusing.

For instance, in the starting code sample, besides the main level of abstraction (getting the final price), there is a mix of other levels of abstractions: error handling, details of price calculation, details of rounding up.

The first 2 have already been removed in the previous steps. Go ahead and make the function cleaner by getting rid of the low level details of rounding up. The improved version will then look like so:

const getProductPrice = async (product, isSaleActive, coupon) => {
  const originalPrice = await getPrice(product);
  product.userCheckedPrice = true;
  const actualPrice = getPriceWithCouponOrSale(originalPrice, product, isSaleActive, coupon);
  return getRoundedValue(actualPrice);
};

This might not look like a big difference, but in reality, such things are like broken windows: once you have one in your code, new ones will add up.

Step 4 — Less arguments the better

The ideal number of arguments is, in order: 0, 1, 2 arguments. Having more than 2 arguments becomes increasingly difficult to reason about, and it might be a sign that your function is doing too many things.

In the previous step, getProductPrice and getPriceWithCouponOrSale use 3, and 4 arguments respectively. This is without doubt difficult to reason about. This can be simplified by simply extracting some of the arguments on top.

Go ahead and try to find ways to pass less arguments to these functions.

In the following proposed solution, this will be done by:

lifting price argument on top of getPriceWithCouponOrSale and make it return a fraction. This function will be renamed to getReducedPriceFraction.
lifting isSaleActive and coupon on top of getProductPrice. They will be replaced with the new reducedPriceFraction.

Here is how the improved code will look like:

const getReducedPriceFraction = (product, isSaleActive, coupon) => {
  if (coupon && coupon.unused && coupon.type === product.type) {
    return 0.5;
  }
  if (isSaleActive) {
    return 0.8;
  }
  return 1;
}

const reducedPriceFraction = getReducedPriceFraction(product, isSaleActive, coupon);

const getProductPrice = async (product, reducedPriceFraction) => {
  const originalPrice = await getPrice(product);
  product.userCheckedPrice = true;
  const actualPrice = originalPrice * reducedPriceFraction;
  return getRoundedValue(actualPrice);
};

This approach can be taken further by repeating it one more time, which leads to the following code, in which getReducedPriceFraction only uses 2 arguments, thus becoming much cleaner:

const isCouponCompatible = (product, coupon) => coupon.type === product.type;

const getReducedPriceFraction = (isSaleActive, isCouponValid) => {
  if (isCouponValid) {
    return 0.5;
  }
  if (isSaleActive) {
    return 0.8;
  }
  return 1;
}

const isCouponValid = coupon && coupon.unused && isCouponCompatible(product, coupon);
const reducedPriceFraction = getReducedPriceFraction(isSaleActive, isCouponValid);

const getProductPrice = async (product, reducedPriceFraction) => {
  const originalPrice = await getPrice(product);
  product.userCheckedPrice = true;
  const actualPrice = originalPrice * reducedPriceFraction;
  return getRoundedValue(actualPrice);
};

Step 5 — No side effects

Side effects make a function do unexpected things. Without having a closer look, you might have missed that getProductPrice function also has a side effect: updating the product object.

This is dangerous because it can cause unexpected behaviours. For instance, in some other part of your code base, you might need to literally only get the product price, and introduce a bug because of this unexpected side effect.

A clean function should do only one thing, without any hidden side effects. Such side effect should instead be done in plain sight, such as at the caller level, or in a separate function called updateProduct.

In our previous code, you can remove the side effect and have it at the caller level (not reproduced). Once removed, you are left with a very clean function:

const getProductPrice = async (product, reducedPriceFraction) => {
  const originalPrice = await getPrice(product);
  const actualPrice = originalPrice * reducedPriceFraction;
  return getRoundedValue(actualPrice);
};

Conclusion

Congratulations! You succeeded in drastically improving the starting code sample by applying these 5 easy principles one by one.

Hopefully this will help you identify opportunities to improve your own code base.

Clean code and clean functions are a joy to read and work on. Spread that joy by writing clean functions!

DEV Community: Manuel Micu

Avoiding CSS style collisions when building a UI widget

The bad approach

Style isolation level

Style customisation level

Approach 1: wrap your widget with an iframe

Approach 2: Side-by-side integrator/widget, with CSS unset isolation

Approach 3: Shadow DOM

Code demo

Visualization of route navigation in a React app

Context in my company

Problem

Solution

Drawing the graph

Running the script

Result

Conclusion

The essence of The Pragmatic Programmer

1. Our job is to help people understand what [requirements] they want.

2. Our job is not just "software developer". It's "problem solver".

How to write clean functions

Introduction

Prerequisites

Step 0 — Starting code

Step 1 — Small

Step 2 — Do one thing

Step 3 — One level of abstraction

Step 4 — Less arguments the better

Step 5 — No side effects

Conclusion

Approach 1: wrap your widget with an `iframe`

Approach 2: Side-by-side integrator/widget, with `CSS unset` isolation