feat(Charts): stabilize new charts and deprecate old charts (#507)

Author: MarcusNotheis

docs/MigrationGuide.md

@@ -1,5 +1,88 @@
 # Migration Guide
 
+## 0.9.5 - Charts Migration
+With version v0.9.5 of `@ui5/webcomponents-react-charts` we replace the canvas based charts with SVG based charts and 
+streamlined the ChartAPI to work similar to the `AnalyticalTable` API.
+This requires a couple of changes on your side:
+
+1. Change the import from `@ui5/webcomponents-react-charts/lib/[ChartType]` to `@ui5/webcomponents-react-charts/lib/[ChartType]`
+2. Don't split the dataset into labels and single dataset entries as before, you can pass your dataset "as-is" to the chart.
+3. Your labels are now part of the dataset, but you need to tell the chart which element of the data is your dimension
+   Use the `dimensions` prop for that.
+4. Instead of passing multiple datasets with their own data into the datasets prop, define your `measures` by specifying at least the `accessor`.
+
+To illustrate the required changes, you can find the migration of a bar chart with two bars per dimension below:
+
+Old Bar Chart:
+```jsx
+import React from 'react';
+import { BarChart } from '@ui5/webcomponents-react-charts/lib/BarChart';
+
+const MyComponent = () => {
+  return (
+    <BarChart
+      labels={['January', 'February', 'March']}
+      datasets={[
+        {
+          label: 'Existing Customers',
+          data: [65, 59, 80]
+        },
+
+        {
+          label: 'New Customers',
+          data: [5, 9, 8]
+        }
+      ]}
+    />
+  );
+};
+```
+
+New Bar Chart:
+```jsx
+import React from 'react';
+import { BarChart } from '@ui5/webcomponents-react-charts/lib/next/BarChart';
+
+const MyComponent = () => {
+  return (
+    <BarChart
+      dimensions={[
+        {
+          accessor: 'month'
+        }
+      ]}
+      measures={[
+        {
+          accessor: 'existingCustomers',
+          label: 'Existing Customers'
+        },
+        {
+          accessor: 'newCustomers',
+          label: 'New Customers'
+        }
+      ]}
+      dataset={[
+        {
+          month: 'January',
+          existingCustomers: 65,
+          newCustomers: 5
+        },
+        {
+          month: 'February',
+          existingCustomers: 59,
+          newCustomers: 9
+        },
+        {
+          month: 'March',
+          existingCustomers: 80,
+          newCustomers: 8
+        }
+      ]}
+    />
+  );
+};
+```
+
 ## Migrating from 0.8.X to 0.9.0
 Migrating your app from 0.8.X to 0.9.0 requires a few updates to the API properties, this includes dependencies, theming, event handling and prop changes.
 

packages/charts/src/components/BarChart/BarChart.tsx

@@ -91,7 +91,6 @@ export interface BarChartProps extends RechartBaseProps {
 
 /**
  * <code>import { BarChart } from '@ui5/webcomponents-react-charts/lib/next/BarChart';</code>
- * **This component is under active development. The API is not stable yet and might change without further notice.**
  */
 const BarChart: FC<BarChartProps> = forwardRef((props: BarChartProps, ref: Ref<any>) => {
   const {
@@ -119,6 +118,7 @@ const BarChart: FC<BarChartProps> = forwardRef((props: BarChartProps, ref: Ref<a
       legendHorizontalAlign: 'left',
       barGap: 3,
       zoomingTool: false,
+      resizeDebounce: 250,
       ...props.chartConfig
     };
   }, [props.chartConfig]);
@@ -174,6 +174,7 @@ const BarChart: FC<BarChartProps> = forwardRef((props: BarChartProps, ref: Ref<a
       className={className}
       tooltip={tooltip}
       slot={slot}
+      resizeDebounce={chartConfig.resizeDebounce}
     >
       <BarChartLib
         margin={marginChart}

packages/charts/src/components/BarChart/BarRechart.stories.tsx

@@ -5,7 +5,7 @@ import React from 'react';
 import { complexDataSet, secondaryDimensionDataSet, simpleDataSet } from '../../resources/DemoProps';
 
 export default {
-  title: 'Charts - Unstable /  BarChart',
+  title: 'Charts /  BarChart',
   component: BarChart
 };
 

packages/charts/src/components/BarChart/demo.stories.tsx

@@ -35,7 +35,7 @@ const options = {
 };
 
 export default {
-  title: 'Charts / BarChart',
+  title: 'Charts - Deprecated / BarChart',
   component: BarChart
 };
 

packages/charts/src/components/BarChart/index.tsx

@@ -1,17 +1,18 @@
+import { getTheme } from '@ui5/webcomponents-base/dist/config/Theme';
 import { useConsolidatedRef } from '@ui5/webcomponents-react-base/lib/useConsolidatedRef';
+import { deprecationNotice } from '@ui5/webcomponents-react-base/lib/Utils';
+import { getTextWidth } from '@ui5/webcomponents-react-charts/lib/Utils';
 import { withChartContainer } from '@ui5/webcomponents-react-charts/lib/withChartContainer';
 import bestContrast from 'get-best-contrast-color';
-import React, { FC, forwardRef, Ref, useMemo } from 'react';
+import React, { FC, forwardRef, Ref, useEffect, useMemo } from 'react';
 import { HorizontalBar } from 'react-chartjs-2';
-import { getTheme } from '@ui5/webcomponents-base/dist/config/Theme';
 import { DEFAULT_OPTIONS } from '../../config';
 import { ChartBaseProps } from '../../interfaces/ChartBaseProps';
 import { InternalProps } from '../../interfaces/InternalProps';
 import { useLegend, useLegendItemClickHandler } from '../../internal/ChartLegend';
 import { getCssVariableValue } from '../../themes/Utils';
 import { ChartBaseDefaultProps } from '../../util/ChartBaseDefaultProps';
 import { useChartData } from '../../util/populateData';
-import { getTextWidth } from '@ui5/webcomponents-react-charts/lib/Utils';
 import { formatAxisCallback, formatDataLabel, formatTooltipLabel, useMergedConfig } from '../../util/utils_deprecated';
 import { BarChartPlaceholder } from './Placeholder';
 
@@ -33,6 +34,13 @@ const BarChartComponent = forwardRef((props: BarChartPropTypes, ref: Ref<any>) =
     legendRef
   } = props as BarChartPropTypes & InternalProps;
 
+  useEffect(() => {
+    deprecationNotice(
+      'BarChart',
+      "This component is deprecated and will be removed with v0.10.0. Please use '@ui5/webcomponents-react-charts/lib/next/BarChart' instead."
+    );
+  }, []);
+
   const theme = getTheme();
   const data = useChartData(labels, datasets, colors, theme);
 
@@ -115,6 +123,8 @@ const BarChartComponent = forwardRef((props: BarChartPropTypes, ref: Ref<any>) =
 BarChartComponent.LoadingPlaceholder = BarChartPlaceholder;
 /**
  * <code>import { BarChart } from '@ui5/webcomponents-react-charts/lib/BarChart';</code>
+ * <br />
+ * <b>This component is deprecated and will be removed with v0.10.0. Please use [this component](https://sap.github.io/ui5-webcomponents-react/?path=/docs/charts-barchart) instead.</b>
  */
 const BarChart: FC<BarChartPropTypes> = withChartContainer(BarChartComponent);
 

packages/charts/src/components/ColumnChart/ColumnChart.tsx

@@ -89,7 +89,6 @@ const measureDefaults = {
 
 /**
  * <code>import { ColumnChart } from '@ui5/webcomponents-react-charts/lib/next/ColumnChart';</code>
- * **This component is under active development. The API is not stable yet and might change without further notice.**
  */
 const ColumnChart: FC<ColumnChartProps> = forwardRef((props: ColumnChartProps, ref: Ref<any>) => {
   const {
@@ -116,6 +115,7 @@ const ColumnChart: FC<ColumnChartProps> = forwardRef((props: ColumnChartProps, r
       legendHorizontalAlign: 'left',
       barGap: 3,
       zoomingTool: false,
+      resizeDebounce: 250,
       ...props.chartConfig
     };
   }, [props.chartConfig]);
@@ -179,6 +179,7 @@ const ColumnChart: FC<ColumnChartProps> = forwardRef((props: ColumnChartProps, r
       className={className}
       tooltip={tooltip}
       slot={slot}
+      resizeDebounce={chartConfig.resizeDebounce}
     >
       <ColumnChartLib
         margin={marginChart}

packages/charts/src/components/ColumnChart/ColumnRechart.stories.tsx

@@ -5,7 +5,7 @@ import React from 'react';
 import { complexDataSet, secondaryDimensionDataSet, simpleDataSet } from '../../resources/DemoProps';
 
 export default {
-  title: 'Charts - Unstable /  ColumnChart',
+  title: 'Charts /  ColumnChart',
   component: ColumnChart
 };
 
@@ -148,7 +148,7 @@ renderCustomDataLabelStory.story = {
   name: 'With formatter'
 };
 
-export const loadingPlaceholder = () => <ColumnChart style={{ width: '30%' }} dimensions={[]} measures={[]}/>;
+export const loadingPlaceholder = () => <ColumnChart style={{ width: '30%' }} dimensions={[]} measures={[]} />;
 
 loadingPlaceholder.story = {
   name: 'Loading placeholder'

packages/charts/src/components/ColumnChart/demo.stories.tsx

@@ -68,7 +68,7 @@ const growthLineOptions = {
 };
 
 export default {
-  title: 'Charts / ColumnChart',
+  title: 'Charts - Deprecated / ColumnChart',
   component: ColumnChart
 };
 

packages/charts/src/components/ColumnChart/index.tsx

@@ -1,9 +1,10 @@
 import { getTheme } from '@ui5/webcomponents-base/dist/config/Theme';
+import { deprecationNotice } from '@ui5/webcomponents-react-base/lib/Utils';
 import { useConsolidatedRef } from '@ui5/webcomponents-react-base/lib/useConsolidatedRef';
 import { getTextHeight, getTextWidth } from '@ui5/webcomponents-react-charts/lib/Utils';
 import { withChartContainer } from '@ui5/webcomponents-react-charts/lib/withChartContainer';
 import bestContrast from 'get-best-contrast-color';
-import React, { FC, forwardRef, Ref, useMemo } from 'react';
+import React, { FC, forwardRef, Ref, useEffect, useMemo } from 'react';
 import { Bar } from 'react-chartjs-2';
 import { DEFAULT_OPTIONS } from '../../config';
 import { ChartBaseProps } from '../../interfaces/ChartBaseProps';
@@ -33,6 +34,13 @@ const ColumnChartComponent = forwardRef((props: ColumnChartPropTypes, ref: Ref<a
     legendRef
   } = props as ColumnChartPropTypes & InternalProps;
 
+  useEffect(() => {
+    deprecationNotice(
+      'ColumnChart',
+      "This component is deprecated and will be removed with v0.10.0. Please use '@ui5/webcomponents-react-charts/lib/next/ColumnChart' instead."
+    );
+  }, []);
+
   const theme = getTheme();
   const data = useChartData(labels, datasets, colors, theme);
 
@@ -118,6 +126,8 @@ const ColumnChartComponent = forwardRef((props: ColumnChartPropTypes, ref: Ref<a
 ColumnChartComponent.LoadingPlaceholder = ColumnChartPlaceholder;
 /**
  * <code>import { ColumnChart } from '@ui5/webcomponents-react-charts/lib/ColumnChart';</code>
+ * <br />
+ * <b>This component is deprecated and will be removed with v0.10.0. Please use [this component](https://sap.github.io/ui5-webcomponents-react/?path=/docs/charts-columnchart) instead.</b>
  */
 const ColumnChart: FC<ColumnChartPropTypes> = withChartContainer(ColumnChartComponent);
 

packages/charts/src/components/ComposedChart/ComposedChart.stories.tsx

@@ -5,7 +5,7 @@ import { bigDataSet, complexDataSet, secondaryDimensionDataSet, simpleDataSet }
 import { boolean, select } from '@storybook/addon-knobs';
 
 export default {
-  title: 'Charts - Unstable /  ComposedChart',
+  title: 'Charts /  ComposedChart',
   component: ComposedChart
 };
 

packages/charts/src/components/ComposedChart/index.tsx

@@ -106,7 +106,6 @@ type AvailableChartTypes = 'line' | 'bar' | 'area' | string;
 
 /**
  * <code>import { ComposedChart } from '@ui5/webcomponents-react-charts/lib/next/ComposedChart';</code>
- * **This component is under active development. The API is not stable yet and might change without further notice.**
  */
 const ComposedChart: FC<ComposedChartProps> = forwardRef((props: ComposedChartProps, ref: Ref<any>) => {
   const {
@@ -135,6 +134,7 @@ const ComposedChart: FC<ComposedChartProps> = forwardRef((props: ComposedChartPr
       legendPosition: 'bottom',
       legendHorizontalAlign: 'left',
       zoomingTool: false,
+      resizeDebounce: 250,
       ...props.chartConfig
     };
   }, [props.chartConfig]);
@@ -223,6 +223,7 @@ const ComposedChart: FC<ComposedChartProps> = forwardRef((props: ComposedChartPr
       className={className}
       tooltip={tooltip}
       slot={slot}
+      resizeDebounce={chartConfig.resizeDebounce}
     >
       <ComposedChartLib
         margin={marginChart}