[charts] Add Heatmap

[alexfauquette]

PoC for #7926

Preview: https://deploy-preview-13209--material-ui-x.netlify.app/x/react-charts/heatmap/

Topics to discuss

The overall strategy

Data Pipeline

For now, charts share the same container that supports line, bar, scatter, and pie series. It allows for mixing them, which is useful for bar+line chart, or scatter + line. But it forces us to put the processing logic of every chart type in the container. Whic is an issue for splitting pro/community code, which puts in your bundle processing you don't need.

Since heatmap (and most of the future components) do not have usecases for mixing with other series types, I propose creating dedicated containers <HeatmapContainer /> based on the same provider, but have only the needed logic.

Another could have been to use <ChartsContainer /> with some props to add the heatmap logic. Whoch would lead to something like

import { heatmapLogic } from '@mui/x-charts-pro';

<ChartsContainer {...heatmapLogic}>
  <HeatmapPlot />
</ChartsContainer>

Maybe the second option is more interesting because it avoids creating a component for each chart, and even if the DX is not incredible, most user will probably use the single component version <Heatmap />, or the composition would be made once and re-exported. The drawback is that the <ChartsContainer /> props will be more complex.

Typing

I modified the TS definition to rely mostly on the ChartsSeriesConfig interface.

The idea is to be able to add any series type by its configuration which represents the series at different stages: from the props provided to the stats stored in the context.

Data format

For now, I went with [x-ndex, y-index, value]

Benchmark

• Nivo: I don't recommend, id is the row, then x is the column, and y the value

{
    id: string
    data: {
        x: string | number
        y: number | null
    }[]
}[]

• Highcharts: same as proposed [number, number, number][]

• Echarts: same as proposed

Another approach could be {x, y, value}[] data type. But we then should handle what append if the x/y value does not have a correct value.

I think both are good, user preferences will mostly depend on the data format returned by their server. So might be better to follow Highcharts/Echarts on this point

Customization

Having a single component

The single component is not yet created, but I wonder if we should simplify the customization, by:

• allowing only one axis. I don't see a usecase with multiple x-axis for a heatmap
• a single zAxis which could be renamed colorScale since its an important aspect of the chart, and we only have one (I can imaging center examples, but not sure they with it)

Follow up

• Add item interaction
• Add tooltip
• Add highlight
• Add legend
• Set good default for the color scale
• Add slots for items
• Theme overrides

[flaviendelangle]

I like the idea of the enhanceable ChartsContainer
Because if we start a HeatmapContainer, I suspect that people will start looking for LineContainer, BarContainer, etc...
So having a single container is IMHO a slightly better DX.

And if we want a single container, then as you said we need to be able to add some logic to this container.

We need to be very sure that we don't need to have several of those pro components in the container, for me we could support an array of plugins (the concept can be named differently):

import { heatMapContainerPlugin } from '@mui/x-charts-pro/Heatmap';

<ChartContainer
  plugins={[heatMapContainerPlugin]}
>
</ChartContainer>

You could even imagine requiring people to do this for some lesser-used community charts in the future to keep the bundle size reasonable.

[JCQuintas]

Since heatmap (and most of the future components) do not have usecases for mixing with other series types, I propose creating dedicated containers based on the same provider, but have only the needed logic.

Another could have been to use with some props to add the heatmap logic. Whoch would lead to something like

import { heatmapLogic } from '@mui/x-charts-pro';

<ChartsContainer {...heatmapLogic}>
  <HeatmapPlot />
</ChartsContainer>

What would be in these heatmapLogic? In theory I like the idea of plugins @flaviendelangle mentioned, but if we need extra ContextProviders it will probably require them to be wrapping components instead.

Data format

It should be fairly straight forward to accept both [x, y, value][] and {x,y,value}[], which the later being easier to read for humans.

Further on data formats, one idea we could start looking at is allowing users to add "transformers" to the dataset, instead of specifying data at a specific format, eg:

const dataset = [
  {
     foo: 1,
     bar: 2,
     baz: 'blue',
     xyz: 'lake',
  }
]

<Chart
  ...
  dataset={dataset}
  series={[{
    transform: (v) => ([v.foo, v.bar, v.baz])
  }]}
/>

Having a single component

You could technically interpolate between 3 colors, but that might be too far fetched 😅

But colorScale probably makes sense if we don't see it being used as anything else

[alexfauquette]

What would be in these heatmapLogic? In theory I like the idea of plugins @flaviendelangle mentioned, but if we need extra ContextProviders it will probably require them to be wrapping components instead.

With the plunging strategy, I could do

pluggins={[
  {
    seriesType: "line",
    seriesFormatter: function,
    xEtremumGetter: function,
    yEtremumGetter: function,
    colorGetter: function,
  },
  {
    seriesType: "bar",
    seriesFormatter: function,
    xEtremumGetter: function,
    yEtremumGetter: function,
    colorGetter: function,
  }
]}

This would provide processing steps to the different providers. Effectively if we need an additional provider we will ned to either

• Add an additional provider
• Create a dedicated charts container
• Add a provider in the current ChartContainer even if not used by existing charts

one idea we could start looking at is allowing users to add "transformers" to the dataset

I'm reluctant to go in the direction of implementing additional kinds of data transformation. When I added the dataset, I got two users worrying about having multiple strategies to provide data to the charts. They said they prefer having a single way of providing data.

From your comment, I conclude that [x, y, v] format is more future proof, because with it we can latter add a step with data={dataset.map(obj => [obj.x, obj.y, obj.value])}. It would be less intuitive to go the other way (from an array of 3 values to an object)

You could technically interpolate between 3 colors, but that might be too far fetched 😅

What do you mean by interpolating between 3 colors ?

[JCQuintas]

With the plunging strategy, I could do

👍 looks good

I'm reluctant to go in the direction of implementing additional kinds of data transformation. When I added the dataset, I got two users worrying about having multiple strategies to provide data to the charts. They said they prefer having a single way of providing data.

I agree the current way data input is handled is a bit confusing, we could delve deeper into that eventually, but I would guess the issue lies in the fact that dataset and series.data are completely different.

My suggestion with transform is that we can have a single source of truth (dataset) and we can apply changes to it, while optimising it for the user.

From your comment, I conclude that [x, y, v] format is more future proof

I don't think

// this
data={dataset.map(obj => [obj.x, obj.y, obj.value])}
// is much different from this
data={dataset.map(([x, y, value]) => ({ x, y, value }))}

Arrays are indeed simpler, but harder for humans to read when you got a lot of data. We can always extend later.

What do you mean by interpolating between 3 colors ?

Nvm, I didn't read your phrase right. I was thinking the user could use the x-axis to define the colors, but we have the colorScale there for that instead 😅

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[mui-bot]

Deploy preview: https://deploy-preview-13209--material-ui-x.netlify.app/

Updated pages:

• docs/data/charts/heatmap/heatmap.md

Generated by 🚫 dangerJS against 198568f

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[oliviertassinari]

It looks like this change introduced https://app.ahrefs.com/site-audit/3523498/data-explorer?columns=pageRating%2Curl%2Ctraffic%2ChttpCode%2Cdepth%2Ccompliant%2CincomingAllLinks%2Corigin&current=12-07-2024T022123&filterId=91013c8aafad4fe1f7a0ad504eccad42&issueId=c64da643-d0f4-11e7-8ed1-001e67ed4656&sorting=-pageRating.

Not all the links in https://mui.com/x/react-charts/tooltip/#api works.

[oliviertassinari]

I find it strange to have this component as ignore ( * @ignore - internal component.) and having a name that is reachable with theme overrides (and normally global CSS too, I mean, I imagine Pigment CSS output clear class names in this context using the name of the styled called, assuming uniqueness property is guaranteed cc @brijeshb42 for context). It feels like it's not completely private nor public.

[oliviertassinari]

Is this correct? I would expect from a public component not to have default.

Suggested change

	export * from './DefaultChartsAxisTooltipContent';
	export * from './ChartsAxisTooltipContent';

If it's a slot, the default part of the name is implicit.