Using Apache ECharts with Lit and TypeScript
Tags: webdev, typescript, echarts, webcomponents
Published: 2024-06-16 12:45:39

### What are Web Components?

[WebComponents.org](https://www.webcomponents.org/introduction) explains it well:

> Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps.

> Custom components and widgets built on the Web Component standards will work across modern browsers and can be used with any JavaScript library or framework that works with HTML.

According to [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), the 3 main APIs for Web Components are:

1. [Custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
2. [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM)
3. [HTML templates](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)

For those interested in learning more, this [CSS-Tricks.com article series](https://css-tricks.com/an-introduction-to-web-components/#aa-article-series) is a great reference.

Since these APIs are all [widely available](https://developer.mozilla.org/en-US/docs/Web/API/Web_components#browser_compatibility), we can start using them to build custom components in production. However, there are libraries like [Lit](https://lit.dev/) and [Stencil](https://stenciljs.com/) that can simplify the development process.

### Why might we need Web Components?

The [FAST Project](https://github.com/microsoft/fast) by Microsoft provides an [in-depth discussion](https://www.fast.design/docs/resources/why-web-components) on the benefits of Web Components.

While [better performance](https://www.fast.design/docs/resources/why-web-components#you-might-choose-web-components-for-performance) may be a reason for some, their framework-agnostic nature was the most important value proposition for our team at [Manufac](https://manufacanalytics.com/). For instance:

1. Your team can build standard Web Components to be reused across different web apps without restricting your developers to a particular framework. This benefit is particularly valuable for large enterprises with multiple teams that have diverse skill sets and preferences.
   
2. If your end product needs to integrate well with any web application, Web Components are ideal. For example, if you're building a payment solution and want to offer a ready-to-use payment button that developers can easily add to their web apps, would you prefer building separate versions for ReactJS, Angular, and VueJS? Or would you rather have a single framework-agnostic UI component?

#### Why not simply use JS/TS to create reusable components programmatically?

You certainly can. One way to do this is to write sub-routines that find, say, all `divs` with specific class names or IDs using methods such as `document.getElementById`, `document.getElementsByClassName`, and `document.querySelector`. You can then replace these elements with the programmatically created UI components of your choice.

However, Web Components offer an additional advantage via its shadow DOM API: **encapsulation**. 

> ... because a custom element, by definition, is a piece of reusable functionality: it might be dropped into any web page and be expected to work. So it's important that code running in the page should not be able to accidentally break a custom element by modifying its internal implementation. Shadow DOM enables you to attach a DOM tree to an element, and have the internals of this tree hidden from JavaScript and CSS running in the page.

MDN provides an in-depth discussion about this [here](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM).

### How can we build a portable choropleth component using Apache ECharts and Lit?

A. Import all the needed dependencies.

I am assuming that you have some familiarity with both Lit and Apache ECharts.

> If not, then the following should help:
> a. [An interactive tutorial for Lit](https://lit.dev/tutorials/intro-to-lit/)
> b. [Getting started with Apache ECharts](https://echarts.apache.org/handbook/en/get-started/)

```ts
import { MapChart } from "echarts/charts";
import {
  TitleComponent,
  ToolboxComponent,
  TooltipComponent,
  VisualMapComponent,
  GeoComponent,
} from "echarts/components";
import { init, use, registerMap } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";
import { LitElement, PropertyValueMap, PropertyValues, html } from "lit";
import { customElement, property, query } from "lit/decorators.js";
import type { MapSeriesOption } from "echarts/charts";
import type {
  TitleComponentOption,
  TooltipComponentOption,
  ToolboxComponentOption,
  GeoComponentOption,
  VisualMapComponentOption,
} from "echarts/components";
import type { ComposeOption, ECharts } from "echarts/core";
import { WorldChoroplethMapGeoJSON } from "./utils";
import { ChoroplethStyles } from "./styles";
```

The `WorldChoroplethMapGeoJSON` imported above is available [here](https://gist.github.com/maneetgoyal/772185d3dd770e1da00a5402a0ce8d7e.js) and `ChoroplethStyles` as shown below can contain your preferred styling:

```ts
import { css } from "lit";

export const ChoroplethStyles = css`
  .choropleth {
    width: 100%;
    height: 100%;
  }
`;
```

B. Next, we'll configure ECharts to do some [bundle size optimization](https://dev.to/manufac/using-apache-echarts-with-react-and-typescript-optimizing-bundle-size-29l8):

```ts
/**
 * Adapted from Echarts.
 * Ref: https://echarts.apache.org/examples/en/editor.html?c=map-usa-projection&lang=ts
 */
type WorldChoroplethMapOptions = ComposeOption<
  | GeoComponentOption
  | MapSeriesOption
  | TitleComponentOption
  | ToolboxComponentOption
  | TooltipComponentOption
  | VisualMapComponentOption
>;

/**
 * Adapted from Echarts.
 * Ref: https://echarts.apache.org/examples/en/editor.html?c=map-usa-projection&lang=ts
 */
use([
  TitleComponent,
  TooltipComponent,
  VisualMapComponent,
  GeoComponent,
  MapChart,
  ToolboxComponent, // A group of utility tools, which includes export, data view, dynamic type switching, data area zooming, and reset.
  CanvasRenderer, // If you only need to use the canvas rendering mode, the bundle will not include the SVGRenderer module, which is not needed.
]);
```

C. Now, we are telling ECharts which [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) file to use to render the base map. This is the world map GeoJSON, but if you only need, say, the Indian or the US map, you can switch the GeoJSON file accordingly.

```ts
/**
 * Adapted from Echarts.
 * Ref: https://echarts.apache.org/examples/en/editor.html?c=map-usa-projection&lang=ts
 */
type RegisterMapParams = Parameters<typeof registerMap>;
registerMap("WorldChoroplethMap", WorldChoroplethMapGeoJSON as RegisterMapParams[1]);
```

D. Next, time for some data modeling. How do we want to express the countries and associated data can be specific to your own use case. Nevertheless, at a basic level, we mainly need some way to <u>identify the country</u> and the <u>associated numeric value to be visualized</u>. In the data model below, we've have a no-frills interface which does just that:


```ts
interface WorldChoroplethDatum {
  name: string;
  value: number;
}
```

The input data passed to the choropleth should now be like this: `WorldChoroplethDatum[]`.

E. Finally, we've come to the core component implementation. You may want to read up a bit on the Lit [lifecycle methods](https://lit.dev/docs/components/lifecycle/) if the following class methods seem foreign:

```ts
/**
 * Using `firstUpdated` alongside `willUpdate` can ensure that the 
 * private variable is set correctly both initially and when properties 
 * change. 
 */
@customElement("world-choropleth")
export class WorldChoropleth extends LitElement {
  #instance: ECharts | undefined;
  #observer: ResizeObserver | undefined;
  #options: WorldChoroplethMapOptions | undefined;

  static styles = [ChoroplethStyles];

  @property({ type: Array })
  value: WorldChoroplethDatum[] = [];

  @property({ type: String })
  title = "";

  // Ref: https://lit.dev/docs/components/shadow-dom/#query
  @query("#choropleth", true)
  private _choropleth: HTMLDivElement | undefined | null;

  protected willUpdate(changedProperties: PropertyValues<this>): void {
    if (changedProperties.has("title")) {
      this.#options = {
        ...this.#options,
        title: { text: changedProperties.get("title") },
      };
    }
    if (changedProperties.has("value")) {
      const newValue = changedProperties.get("value") ?? [];
      const values = newValue.map((ele) => ele.value);
      this.#options = {
        ...this.#options,
        series: {
          ...(this.#options?.series as MapSeriesOption),
          data: newValue,
        },
        visualMap: {
          ...this.#options?.visualMap,
          min: Math.min(...values),
          max: Math.max(...values),
        },
      };
    }
  }

  protected firstUpdated = () => {
    // Initialize echarts instance
    if (this._choropleth !== null && this._choropleth !== undefined) {
      this.#instance = init(this._choropleth);
      this.#observer = new ResizeObserver(() => {
        this.#instance?.resize();
      });
      this.#observer.observe(this._choropleth);
      const values = this.value.map((ele) => ele.value);
      this.#options = {
        title: {
          left: "center",
          text: this.title,
        },
        tooltip: {
          trigger: "item",
          showDelay: 0,
          transitionDuration: 0.2,
        },
        toolbox: {
          show: true,
          left: "right",
          top: "top",
          feature: {
            saveAsImage: {},
            restore: {
              show: true,
              title: "Reset zoom",
            },
          },
        },
        visualMap: {
          id: "visual-map",
          type: "continuous",
          left: "right",
          min: Math.min(...values),
          max: Math.max(...values),
          inRange: {
            color: [
              "#313695",
              "#4575b4",
              "#74add1",
              "#abd9e9",
              "#e0f3f8",
              "#ffffbf",
              "#fee090",
              "#fdae61",
              "#f46d43",
              "#d73027",
              "#a50026",
            ],
          },
          text: ["High", "Low"],
          calculable: true,
          realtime: false,
        },
        series: {
          id: "WorldChoroplethMapSeries",
          name: "WorldChoroplethMap",
          type: "map",
          map: "WorldChoroplethMap", // Should be same as the map registered with 'registerMap'
          roam: true, // Used for zooming and spanning over the map. Ref: https://echarts.apache.org/en/option.html#series-map.roam
          /**
           * Associates individual map polygons to the key defined.
           * Ref: https://echarts.apache.org/en/option.html#series-map.nameProperty
           */
          nameProperty: "name",
          data: this.value,
        },
      };
    }
  };

  protected updated(_changedProperties: PropertyValues<this>): void {
    if (this.#options !== undefined) {
      this.#instance?.setOption(this.#options);
    }
  }

  disconnectedCallback(): void {
    super.disconnectedCallback();
    this.#observer?.disconnect();
    this.#instance?.dispose();
  }

  render() {
    return html`<div id="choropleth" class="choropleth"></div>`;
  }
}
```

### Why those lifecycle methods were used?

A. Why `willUpdate`?

It is a lifecycle method that gets called before the component updates. It is often used to perform operations that need to happen just before the update occurs, such as making changes to the state or properties based on the current and upcoming values.

In our case: Before updating, this method checks if the `title` or `value` properties have changed. If they have, it updates the `#options` object with new values. This prepares the component's state before the actual rendering.

B. Why `firstUpdated`?

It is called after the component's initial render, i.e., after the component has been added to the DOM for the first time. It’s used to perform tasks that require the component to be fully rendered and part of the DOM, such as interacting with the DOM, initializing third-party libraries, or setting up event listeners. It runs only once, immediately after the component's first render.

In our case: After the initial render, this method initializes the ECharts instance, sets up a `ResizeObserver` to handle resizing, and configures the chart options using the component's properties.

C. Why `updated`?

It is called after the component's update has been rendered to the DOM. It allows you to perform operations after the component has updated, such as interacting with the DOM based on new properties or states. It runs after each update (initial and subsequent updates).

In our case: After the component updates, this method sets the new options for the ECharts instance, ensuring that the chart reflects the latest data and configuration.

D. Why `disconnectedCallback`?

It is a lifecycle method that is invoked when a component is removed from the DOM. This method is useful for performing cleanup tasks such as removing event listeners, canceling timers, or cleaning up any other resources that the component might have allocated. It runs when the component is detached from the DOM, such as when it is removed or replaced.

In our case: When the component is removed from the DOM, this method disconnects the `ResizeObserver` and disposes off the ECharts instance to clean up resources and consequently, prevent memory leaks.

### How can you consume such a component in your apps?

You can find some quick instructions in the official Lit docs [here](https://lit.dev/docs/tools/adding-lit/#use-your-component). For ReactJS, Lit provides additional support; this [integration guide](https://lit.dev/docs/frameworks/react/) will be very helpful.

If you'd like to consume the same choropleth component share above, it can be easily installed via NPM:

```bash
yarn add @manufac/web-components
```

Further, we have added some example integrations in CodeSandbox to simplify the process:

1. [For a vanilla web app](https://codesandbox.io/p/devbox/world-chorpleth-web-component-in-vanilla-web-app-pqprvs)
2. [For a ReactJS web app](https://codesandbox.io/p/devbox/world-choropleth-web-component-in-reactjs-app-wgjh67)

These examples should help you get started quickly and more conveniently.

***

Interested in learning how web components can be added to Wordpress blogs/sites? Let us know in the comments and we'll be happy to share another blog for the same. 🧑‍💻😀👋

Do consider web components for your framework agnostic UI requirements; they just might be what you need!

****