feat: Adds the ECharts Histogram chart (#28652)

superset-frontend/plugins/plugin-chart-echarts/src/Histogram/Histogram.tsx

@@ -0,0 +1,61 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import React from 'react';
+import { HistogramTransformedProps } from './types';
+import Echart from '../components/Echart';
+import { EventHandlers } from '../types';
+
+export default function Histogram(props: HistogramTransformedProps) {
+  const {
+    height,
+    width,
+    echartOptions,
+    onFocusedSeries,
+    onLegendStateChanged,
+    refs,
+  } = props;
+
+  const eventHandlers: EventHandlers = {
+    legendselectchanged: payload => {
+      onLegendStateChanged?.(payload.selected);
+    },
+    legendselectall: payload => {
+      onLegendStateChanged?.(payload.selected);
+    },
+    legendinverseselect: payload => {
+      onLegendStateChanged?.(payload.selected);
+    },
+    mouseout: () => {
+      onFocusedSeries(undefined);
+    },
+    mouseover: params => {
+      onFocusedSeries(params.seriesIndex);
+    },
+  };
+
+  return (
+    <Echart
+      refs={refs}
+      height={height}
+      width={width}
+      echartOptions={echartOptions}
+      eventHandlers={eventHandlers}
+    />
+  );
+}

superset-frontend/plugins/plugin-chart-echarts/src/Histogram/buildQuery.ts

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { buildQueryContext } from '@superset-ui/core';
+import { histogramOperator } from '@superset-ui/chart-controls';
+import { HistogramFormData } from './types';
+
+export default function buildQuery(formData: HistogramFormData) {
+  const { column, groupby = [] } = formData;
+  return buildQueryContext(formData, baseQueryObject => [
+    {
+      ...baseQueryObject,
+      columns: [...groupby, column],
+      post_processing: [histogramOperator(formData, baseQueryObject)],
+    },
+  ]);
+}

superset-frontend/plugins/plugin-chart-echarts/src/Histogram/controlPanel.tsx

@@ -0,0 +1,141 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import {
+  GenericDataType,
+  t,
+  validateInteger,
+  validateNonEmpty,
+} from '@superset-ui/core';
+import {
+  ControlPanelConfig,
+  formatSelectOptionsForRange,
+  dndGroupByControl,
+  columnsByType,
+} from '@superset-ui/chart-controls';
+import { showLegendControl, showValueControl } from '../controls';
+
+const config: ControlPanelConfig = {
+  controlPanelSections: [
+    {
+      label: t('Query'),
+      expanded: true,
+      controlSetRows: [
+        [
+          {
+            name: 'column',
+            config: {
+              ...dndGroupByControl,
+              label: t('Column'),
+              multi: false,
+              description: t('Numeric column used to calculate the histogram.'),
+              validators: [validateNonEmpty],
+              freeForm: false,
+              disabledTabs: new Set(['saved', 'sqlExpression']),
+              mapStateToProps: ({ datasource }) => ({
+                options: columnsByType(datasource, GenericDataType.Numeric),
+              }),
+            },
+          },
+        ],
+        ['groupby'],
+        ['adhoc_filters'],
+        ['row_limit'],
+        [
+          {
+            name: 'bins',
+            config: {
+              type: 'SelectControl',
+              freeForm: true,
+              label: t('Bins'),
+              default: 5,
+              choices: formatSelectOptionsForRange(5, 20, 5),
+              description: t('The number of bins for the histogram'),
+              validators: [validateInteger],
+            },
+          },
+        ],
+        [
+          {
+            name: 'normalize',
+            config: {
+              type: 'CheckboxControl',
+              label: t('Normalize'),
+              description: t(`
+                The normalize option transforms the histogram values into proportions or
+                probabilities by dividing each bin's count by the total count of data points.
+                This normalization process ensures that the resulting values sum up to 1,
+                enabling a relative comparison of the data's distribution and providing a
+                clearer understanding of the proportion of data points within each bin.`),
+              default: false,
+            },
+          },
+        ],
+        [
+          {
+            name: 'cumulative',
+            config: {
+              type: 'CheckboxControl',
+              label: t('Cumulative'),
+              description: t(`
+                The cumulative option allows you to see how your data accumulates over different
+                values. When enabled, the histogram bars represent the running total of frequencies
+                up to each bin. This helps you understand how likely it is to encounter values
+                below a certain point. Keep in mind that enabling cumulative doesn't change your
+                original data, it just changes the way the histogram is displayed.`),
+              default: false,
+            },
+          },
+        ],
+      ],
+    },
+    {
+      label: t('Chart Options'),
+      expanded: true,
+      controlSetRows: [
+        ['color_scheme'],
+        [showValueControl],
+        [showLegendControl],
+        [
+          {
+            name: 'x_axis_title',
+            config: {
+              type: 'TextControl',
+              label: t('X Axis Title'),
+              renderTrigger: true,
+              default: '',
+            },
+          },
+        ],
+        [
+          {
+            name: 'y_axis_title',
+            config: {
+              type: 'TextControl',
+              label: t('Y Axis Title'),
+              renderTrigger: true,
+              default: '',
+            },
+          },
+        ],
+      ],
+    },
+  ],
+};
+
+export default config;

superset-frontend/plugins/plugin-chart-echarts/src/Histogram/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regardin
+ * g copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { Behavior, ChartMetadata, ChartPlugin, t } from '@superset-ui/core';
+import buildQuery from './buildQuery';
+import controlPanel from './controlPanel';
+import transformProps from './transformProps';
+import thumbnail from './images/thumbnail.png';
+import example1 from './images/example1.png';
+import example2 from './images/example2.png';
+import { HistogramChartProps, HistogramFormData } from './types';
+
+export default class EchartsHistogramChartPlugin extends ChartPlugin<
+  HistogramFormData,
+  HistogramChartProps
+> {
+  /**
+   * The constructor is used to pass relevant metadata and callbacks that get
+   * registered in respective registries that are used throughout the library
+   * and application. A more thorough description of each property is given in
+   * the respective imported file.
+   *
+   * It is worth noting that `buildQuery` and is optional, and only needed for
+   * advanced visualizations that require either post processing operations
+   * (pivoting, rolling aggregations, sorting etc) or submitting multiple queries.
+   */
+  constructor() {
+    super({
+      buildQuery,
+      controlPanel,
+      loadChart: () => import('./Histogram'),
+      metadata: new ChartMetadata({
+        behaviors: [Behavior.InteractiveChart],
+        credits: ['https://echarts.apache.org'],
+        category: t('Distribution'),
+        description: t(
+          `The histogram chart displays the distribution of a dataset by
+          representing the frequency or count of values within different ranges or bins.
+          It helps visualize patterns, clusters, and outliers in the data and provides
+          insights into its shape, central tendency, and spread.`,
+        ),
+        exampleGallery: [{ url: example1 }, { url: example2 }],
+        name: t('Histogram'),
+        tags: [t('Comparison'), t('ECharts'), t('Pattern'), t('Range')],
+        thumbnail,
+      }),
+      transformProps,
+    });
+  }
+}

superset-frontend/plugins/plugin-chart-echarts/src/Histogram/transformProps.ts

@@ -0,0 +1,188 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { BarSeriesOption, EChartsOption } from 'echarts';
+import { CallbackDataParams } from 'echarts/types/src/util/types';
+import { isEmpty } from 'lodash';
+import {
+  CategoricalColorNamespace,
+  NumberFormats,
+  getColumnLabel,
+  getNumberFormatter,
+  tooltipHtml,
+} from '@superset-ui/core';
+import { HistogramChartProps, HistogramTransformedProps } from './types';
+import { LegendOrientation, LegendType, Refs } from '../types';
+import { defaultGrid, defaultYAxis } from '../defaults';
+import { getLegendProps } from '../utils/series';
+import { getDefaultTooltip } from '../utils/tooltip';
+import { getPercentFormatter } from '../utils/formatters';
+
+export default function transformProps(
+  chartProps: HistogramChartProps,
+): HistogramTransformedProps {
+  const refs: Refs = {};
+  let focusedSeries: number | undefined;
+  const {
+    formData,
+    height,
+    hooks,
+    legendState = {},
+    queriesData,
+    theme,
+    width,
+  } = chartProps;
+  const { onLegendStateChanged } = hooks;
+  const {
+    colorScheme,
+    column,
+    groupby = [],
+    normalize,
+    showLegend,
+    showValue,
+    sliceId,
+    xAxisTitle,
+    yAxisTitle,
+  } = formData;
+  const { data } = queriesData[0];
+  const colorFn = CategoricalColorNamespace.getScale(colorScheme);
+  const formatter = getNumberFormatter(
+    normalize ? NumberFormats.FLOAT_2_POINT : NumberFormats.INTEGER,
+  );
+  const percentFormatter = getPercentFormatter(NumberFormats.PERCENT_2_POINT);
+  const groupbySet = new Set(groupby);
+  const xAxisData: string[] = Object.keys(data[0]).filter(
+    key => !groupbySet.has(key),
+  );
+  const barSeries: BarSeriesOption[] = data.map(datum => {
+    const seriesName =
+      groupby.length > 0
+        ? groupby.map(key => datum[getColumnLabel(key)]).join(', ')
+        : getColumnLabel(column);
+    const seriesData = Object.keys(datum)
+      .filter(key => groupbySet.has(key) === false)
+      .map(key => datum[key] as number);
+    return {
+      name: seriesName,
+      type: 'bar',
+      data: seriesData,
+      itemStyle: {
+        color: colorFn(seriesName, sliceId),
+      },
+      label: {
+        show: showValue,
+        position: 'top',
+        formatter: params => {
+          const { value } = params;
+          return formatter.format(value as number);
+        },
+      },
+    };
+  });
+
+  const legendOptions = barSeries.map(series => series.name as string);
+  if (isEmpty(legendState)) {
+    legendOptions.forEach(legend => {
+      legendState[legend] = true;
+    });
+  }
+
+  const tooltipFormatter = (params: CallbackDataParams[]) => {
+    const title = params[0].name;
+    const rows = params.map(param => {
+      const { marker, seriesName, value } = param;
+      return [`${marker}${seriesName}`, formatter.format(value as number)];
+    });
+    if (groupby.length > 0) {
+      const total = params.reduce(
+        (acc, param) => acc + (param.value as number),
+        0,
+      );
+      if (!normalize) {
+        rows.forEach((row, i) =>
+          row.push(
+            percentFormatter.format((params[i].value as number) / (total || 1)),
+          ),
+        );
+      }
+      const totalRow = ['Total', formatter.format(total)];
+      if (!normalize) {
+        totalRow.push(percentFormatter.format(1));
+      }
+      rows.push(totalRow);
+    }
+    return tooltipHtml(rows, title, focusedSeries);
+  };
+
+  const onFocusedSeries = (index?: number | undefined) => {
+    focusedSeries = index;
+  };
+
+  const echartOptions: EChartsOption = {
+    grid: {
+      ...defaultGrid,
+      bottom: 30,
+      left: 30,
+      right: 30,
+    },
+    xAxis: {
+      data: xAxisData,
+      name: xAxisTitle,
+      nameGap: 35,
+      type: 'category',
+      nameLocation: 'middle',
+    },
+    yAxis: {
+      ...defaultYAxis,
+      name: yAxisTitle,
+      nameGap: normalize ? 55 : 40,
+      type: 'value',
+      nameLocation: 'middle',
+      axisLabel: {
+        formatter: (value: number) => formatter.format(value),
+      },
+    },
+    series: barSeries,
+    legend: {
+      ...getLegendProps(
+        LegendType.Scroll,
+        LegendOrientation.Top,
+        showLegend,
+        theme,
+        false,
+        legendState,
+      ),
+      data: legendOptions,
+    },
+    tooltip: {
+      ...getDefaultTooltip(refs),
+      trigger: 'axis',
+      formatter: tooltipFormatter,
+    },
+  };
+
+  return {
+    refs,
+    formData,
+    width,
+    height,
+    echartOptions,
+    onFocusedSeries,
+    onLegendStateChanged,
+  };
+}

superset-frontend/plugins/plugin-chart-echarts/src/Histogram/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { QueryFormColumn, QueryFormData } from '@superset-ui/core';
+import { BaseChartProps, BaseTransformedProps } from '../types';
+
+export type HistogramFormData = QueryFormData & {
+  bins: number;
+  column: QueryFormColumn;
+  colorScheme?: string;
+  cumulative: boolean;
+  normalize: boolean;
+  sliceId: number;
+  showLegend: boolean;
+  showValue: boolean;
+  xAxisTitle: string;
+  yAxisTitle: string;
+};
+
+export interface HistogramChartProps extends BaseChartProps<HistogramFormData> {
+  formData: HistogramFormData;
+}
+
+export type HistogramTransformedProps =
+  BaseTransformedProps<HistogramFormData> & {
+    onFocusedSeries: (index: number | undefined) => void;
+  };

superset-frontend/plugins/plugin-chart-echarts/src/controls.tsx

@@ -34,7 +34,7 @@ import { defaultXAxis } from './defaults';
 const { legendMargin, legendOrientation, legendType, showLegend } =
   DEFAULT_LEGEND_FORM_DATA;
 
-const showLegendControl: ControlSetItem = {
+export const showLegendControl: ControlSetItem = {
   name: 'show_legend',
   config: {
     type: 'CheckboxControl',

superset-frontend/plugins/plugin-chart-echarts/src/index.ts

@@ -28,6 +28,7 @@ export { default as EchartsMixedTimeseriesChartPlugin } from './MixedTimeseries'
 export { default as EchartsPieChartPlugin } from './Pie';
 export { default as EchartsGraphChartPlugin } from './Graph';
 export { default as EchartsGaugeChartPlugin } from './Gauge';
+export { default as EchartsHistogramChartPlugin } from './Histogram';
 export { default as EchartsRadarChartPlugin } from './Radar';
 export { default as EchartsFunnelChartPlugin } from './Funnel';
 export { default as EchartsTreeChartPlugin } from './Tree';
@@ -56,6 +57,7 @@ export { default as HeatmapTransformProps } from './Heatmap/transformProps';
 export { default as SunburstTransformProps } from './Sunburst/transformProps';
 export { default as BubbleTransformProps } from './Bubble/transformProps';
 export { default as WaterfallTransformProps } from './Waterfall/transformProps';
+export { default as HistogramTransformProps } from './Histogram/transformProps';
 
 export { DEFAULT_FORM_DATA as TimeseriesDefaultFormData } from './Timeseries/constants';