[RFC] Server-Side Render and Light Client Hydration Runtime

Problem

Apache ECharts's package size is about 300KB to 1MB after minification, which is sometimes unacceptable for mobile users. ECharts's Server Side Rendering (SSR) solution can solve this problem to a great extent. But users cannot interact directly with the server-rendered image (with Canvas SSR) or SVG (with SVG SSR).

To solve this problem, Client Side Hydration is usually used (see Vue and React Client Side Hydration document). But for Apache ECharts, this means we still need to load the 300KB to 1MB package, which is still undesired for some situations. So a light runtime is probably needed to enable user interaction.

2023-03-01-17-10-19-image

Goal

SVG SSR seems to be a more promising solution because the shapes are preserved in the result, not to mention a lot of other benefits. Currently, the SVG rendering result consists of primary shapes like rectangles with position and size attributes, but we have no idea if it's a bar of a bar series or a legend item and thus the client runtime has no idea how to bind the interaction.

So we need to perserve some meta data when doing SSR, e.g., which series or components this shape belongs to. The meta data is a seperate JSON string.

Scope

The client side runtime should provide the abilities to enable the interaction of:

Changing the style (color/border-width/border-color/...) of the series items when users hover/select/blur the series
Showing/hiding of a series when clicking legend items
Showing/hiding the tooltip when hovering on series items
Animation after another SSR with a new option

And the following are the advanced features that may NOT be supported (at least for now):

Showing/hiding axisPointer
Data-zooming
Bar racing
Line racing
Dragging to change the item positions

If these interactions are required for some cases, the developer should consider using the regular Apache ECharts library to do the hydration after SSR.

Design

Attributes in The SVG Node

Aim: Shape styles may change when interacting. For example, when hovering on a bar in a bar series, the color of the bar series may change to be emphasis.itemStyle.color. So we need to add this information to the CSS style of each SVG node representing a Displayable. In order to constrain the SVG size, we create CSS classes to reuse the same style.

Generation stage: When in _paintList of the SVG painter, each Displayable should be checked if is special (e.g., part of series item or legend item), and add the hovering style with CSS names.

Extra SVG Attributes:

Attribute	Type	Explanation
ecmeta_type	"seriesItem" \| "legendItem"	"seriesItem": This SVG shape is part of the series item. For example, a sector in a pie series, or a circle or a line in a line series. "legendItem": The shapes and the text for a legend item.
ecmeta_seriesindex	number	For "seriesItem" type, it means the series index which this shape belongs to. For "legendItem", it means which series to toggle when clicking.
ecmeta_dataindex	number	For "seriesItem" type, it means the data index which this shape belongs to. For "legendItem", it means which data to toggle when clicking.

Client Hydration

The Client hydration runtime code size is very small. It binds the events of the SVG nodes and triggers events that we care about (clicking the legend items, or clicking the series items).

Examples

I made a complete demo of SSR and Client Runtime. I think this demo can better illustrate the usage.

Discussion

This client hydration runtime can solve the package size issue, especially for mobile conditions. Although it has many limitations as compared to loading a full ECharts code on the client side, I do believe this can offer great help for many cases.

The client runtime is currently including in the test file of this PR. In the future, I think it can be put in a seperate repo under Apache on GitHub.

Any discussion is welcomed! :)

apache / echarts