feat(chart-provider): add component to wrap charts

.changeset/cyan-lemons-kneel.md

@@ -0,0 +1,5 @@
+---
+"@twilio-paste/codemods": minor
+---
+
+[ChartProvider] added a new component that will wrap chart instances to control and share the state to child charting components

.changeset/popular-plants-search.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/chart-provider": major
+"@twilio-paste/core": minor
+---
+
+[ChartProvider] added a new component that will wrap chart instances to control and share the state to child charting components

.codesandbox/ci.json

@@ -21,6 +21,7 @@
     "/packages/paste-core/components/button-group",
     "/packages/paste-core/components/callout",
     "/packages/paste-core/components/card",
+    "/packages/paste-core/components/chart-provider",
     "/packages/paste-core/components/chat-composer",
     "/packages/paste-core/components/chat-log",
     "/packages/paste-core/components/checkbox",

packages/paste-codemods/tools/.cache/mappings.json

@@ -48,6 +48,8 @@
   "CalloutListItem": "@twilio-paste/core/callout",
   "CalloutText": "@twilio-paste/core/callout",
   "Card": "@twilio-paste/core/card",
+  "ChartContext": "@twilio-paste/core/chart-provider",
+  "ChartProvider": "@twilio-paste/core/chart-provider",
   "ChatComposer": "@twilio-paste/core/chat-composer",
   "ChatComposerActionGroup": "@twilio-paste/core/chat-composer",
   "ChatComposerAttachmentCard": "@twilio-paste/core/chat-composer",

packages/paste-core/components/chart-provider/__tests__/index.spec.tsx

@@ -0,0 +1,31 @@
+import { render } from "@testing-library/react";
+import { BoxProps } from "@twilio-paste/box";
+import * as React from "react";
+
+import { ChartProvider } from "../src";
+
+const TestChartProvider: React.FC<React.PropsWithChildren<{ element?: BoxProps["element"] }>> = ({
+  element,
+  children,
+}) => {
+  return (
+    <ChartProvider highchartsOptions={{}} data-testid="chart-provider" element={element}>
+      {children}
+    </ChartProvider>
+  );
+};
+
+describe("ChartProvider", () => {
+  it("should render", () => {
+    const { getByText, getByTestId } = render(<TestChartProvider>test</TestChartProvider>);
+    expect(getByText("test")).toBeDefined();
+    expect(getByTestId("chart-provider").getAttribute("data-paste-element")).toEqual("CHART_PROVIDER");
+  });
+
+  describe("Customization", () => {
+    it("should apply the element prop", () => {
+      const { getByTestId } = render(<TestChartProvider element="TEST_ELEMENT" />);
+      expect(getByTestId("chart-provider").getAttribute("data-paste-element")).toEqual("TEST_ELEMENT");
+    });
+  });
+});

packages/paste-core/components/chart-provider/build.js

@@ -0,0 +1,3 @@
+const { build } = require("../../../../tools/build/esbuild");
+
+build(require("./package.json"));

packages/paste-core/components/chart-provider/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@twilio-paste/chart-provider",
+  "version": "0.0.0",
+  "category": "data display",
+  "status": "beta",
+  "description": "Chart Provider is a data visualization component used to wrap an individual chart to store and share state to child charting elements.",
+  "author": "Twilio Inc.",
+  "license": "MIT",
+  "main:dev": "src/index.tsx",
+  "main": "dist/index.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "yarn clean && NODE_ENV=production node build.js && tsc",
+    "build:js": "NODE_ENV=development node build.js",
+    "build:typedocs": "tsx ../../../../tools/build/generate-type-docs",
+    "clean": "rm -rf ./dist",
+    "tsc": "tsc"
+  },
+  "peerDependencies": {
+    "@twilio-paste/animation-library": "^2.0.0",
+    "@twilio-paste/box": "^10.2.0",
+    "@twilio-paste/color-contrast-utils": "^5.0.0",
+    "@twilio-paste/customization": "^8.1.1",
+    "@twilio-paste/design-tokens": "^10.3.0",
+    "@twilio-paste/style-props": "^9.1.1",
+    "@twilio-paste/styling-library": "^3.0.0",
+    "@twilio-paste/theme": "^11.0.1",
+    "@twilio-paste/types": "^6.0.0",
+    "@types/react": "^16.8.6 || ^17.0.2 || ^18.0.27",
+    "@types/react-dom": "^16.8.6 || ^17.0.2 || ^18.0.10",
+    "highcharts": "^9.3.3",
+    "react": "^16.8.6 || ^17.0.2 || ^18.0.0",
+    "react-dom": "^16.8.6 || ^17.0.2 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@twilio-paste/animation-library": "^2.0.0",
+    "@twilio-paste/box": "^10.2.0",
+    "@twilio-paste/color-contrast-utils": "^5.0.0",
+    "@twilio-paste/customization": "^8.1.1",
+    "@twilio-paste/design-tokens": "^10.3.0",
+    "@twilio-paste/style-props": "^9.1.1",
+    "@twilio-paste/styling-library": "^3.0.0",
+    "@twilio-paste/theme": "^11.0.1",
+    "@twilio-paste/types": "^6.0.0",
+    "@types/react": "^18.0.27",
+    "@types/react-dom": "^18.0.10",
+    "highcharts": "^9.3.3",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^4.9.4"
+  }
+}

packages/paste-core/components/chart-provider/src/ChartContext.tsx

@@ -0,0 +1,68 @@
+import * as Highcharts from "highcharts";
+import * as React from "react";
+
+export interface ChartContextProps {
+  /**
+   * The function that will be called by the HighchartsReact callback to set the chart object in the context.
+   *
+   * @param {Function} chart - the chart object returned from the HighchartsReact callback
+   * @memberof ChartContextProps
+   */
+  setChart: (chart: Highcharts.Chart) => void;
+  /**
+   * Used to the set the reference to the chart element once it is populated
+   *
+   * @param {HTMLElement} ref - React.MutableRefObject.current of base chart component
+   * @memberof ChartContextProps
+   */
+  setChartRef: (ref: HTMLElement) => void;
+  /**
+   * The options that will be passed to the ReactHighcharts component. It will be enriched with tracking events that wil be used by
+   * other Paste components if using the ChartProvider.
+   *
+   * @type {Highcharts.Options}
+   * @memberof ChartContextProps
+   */
+  options: Highcharts.Options;
+  /**
+   * The rendered chart returned from the HighchartsReact callback. Use this object to get the rendered properties of
+   * series and points when calculating poitioning of custom elements. It can also be used to interact
+   * with the chart in ways such as setting zoom levels and using chart.update to trigger changes.
+   *
+   * @type {Highcharts.Chart}
+   * @memberof ChartContextProps
+   */
+  chart?: Highcharts.Chart;
+
+  /**
+   * The current reference to the base chart component. Needed for positioning custom elements relative to points.
+   *
+   * @type {string}
+   * @memberof ChartContextProps
+   */
+  chartRef?: HTMLElement;
+  /**
+   * The current chart type. Used to trigger rerenders of other components inside ChartProvider.
+   *
+   * @type {string}
+   * @memberof ChartContextProps
+   */
+  chartType?: string;
+}
+
+/**
+ * Setting the default values to log errors is an alternative to throwing runtime errors that still allow engineers
+ *  to debug any potential issues.
+ */
+
+export const ChartContext = React.createContext<ChartContextProps>({
+  options: {},
+  setChart: () => {
+    // eslint-disable-next-line no-console
+    console.error("setChart not implemented. Is this component wrapped in the ChartProvider component?");
+  },
+  setChartRef: () => {
+    // eslint-disable-next-line no-console
+    console.error("setChartRef not implemented. Is this component wrapped in the ChartProvider component?");
+  },
+});

packages/paste-core/components/chart-provider/src/ChartProvider.tsx

@@ -0,0 +1,58 @@
+import { Box, safelySpreadBoxProps } from "@twilio-paste/box";
+import type { BoxProps } from "@twilio-paste/box";
+import type { HTMLPasteProps } from "@twilio-paste/types";
+import * as Highcharts from "highcharts";
+import * as React from "react";
+
+import { ChartContext } from "./ChartContext";
+
+interface BaseChartProviderProps extends HTMLPasteProps<"div"> {
+  children?: React.ReactNode;
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default 'CHART_PROVIDER'
+   * @type {BoxProps['element']}
+   * @memberof ChartProviderProps
+   */
+  element?: BoxProps["element"];
+}
+
+interface HighchartsOptions extends BaseChartProviderProps {
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default null
+   * @type {BoxProps['element']}
+   * @memberof ChartProviderProps
+   */
+  highchartsOptions: Highcharts.Options;
+  pasteOptions?: never;
+}
+
+export type ChartProviderProps = HighchartsOptions;
+
+const ChartProvider = React.forwardRef<HTMLDivElement, ChartProviderProps>(
+  ({ element = "CHART_PROVIDER", children, highchartsOptions, ...props }, ref) => {
+    const [chart, setChart] = React.useState<Highcharts.Chart>();
+    const [chartRef, setChartRef] = React.useState<HTMLElement>();
+
+    return (
+      <Box {...safelySpreadBoxProps(props)} ref={ref} element={element} position="relative">
+        <ChartContext.Provider
+          value={{
+            chart,
+            setChart,
+            chartRef,
+            setChartRef,
+            options: highchartsOptions,
+          }}
+        >
+          {children}
+        </ChartContext.Provider>
+      </Box>
+    );
+  },
+);
+
+ChartProvider.displayName = "ChartProvider";
+
+export { ChartProvider };

packages/paste-core/components/chart-provider/src/index.tsx

@@ -0,0 +1,3 @@
+export { ChartProvider } from "./ChartProvider";
+export type { ChartProviderProps } from "./ChartProvider";
+export { ChartContext } from "./ChartContext";

packages/paste-core/components/chart-provider/stories/BaseChart.tsx

@@ -0,0 +1,45 @@
+import { Box } from "@twilio-paste/box";
+import { usePasteHighchartsTheme } from "@twilio-paste/data-visualization-library";
+import * as Highcharts from "highcharts";
+import HighchartsReact from "highcharts-react-official";
+import * as React from "react";
+
+import { ChartContext } from "../src";
+
+const Chart: React.FC = () => {
+  const chartRef = React.useRef<HTMLElement | null>(null);
+  const { options, setChart, setChartRef } = React.useContext(ChartContext);
+  const [chartOptions, setChartOptions] = React.useState<Highcharts.Options>(
+    usePasteHighchartsTheme({ ...options, plotOptions: { series: { animation: false } } }),
+  );
+
+  React.useLayoutEffect(() => {
+    setChartOptions(Highcharts.merge(chartOptions, options));
+  }, [options]);
+
+  React.useEffect(() => {
+    if (chartRef.current) {
+      setChartRef(chartRef.current);
+    }
+  }, [chartRef.current]);
+
+  const callback = (chart: Highcharts.Chart): void => {
+    if (chart?.series?.length > 0) {
+      setChart(chart);
+    }
+  };
+
+  return (
+    <Box gridArea="base-chart" ref={chartRef} position="relative">
+      <HighchartsReact
+        highcharts={Highcharts}
+        options={chartOptions}
+        constructorType={chartOptions.chart?.map ? "mapChart" : undefined}
+        updateArgs={[true, true, false]}
+        callback={callback}
+      />
+    </Box>
+  );
+};
+
+export const BaseChart = React.memo(Chart);

packages/paste-core/components/chart-provider/stories/index.stories.tsx

@@ -0,0 +1,50 @@
+import type { StoryFn } from "@storybook/react";
+import { Box } from "@twilio-paste/box";
+import { Button } from "@twilio-paste/button";
+import { Paragraph } from "@twilio-paste/paragraph";
+import { Theme } from "@twilio-paste/theme";
+import * as React from "react";
+
+import { ChartContext, ChartProvider } from "../src";
+import { BaseChart } from "./BaseChart";
+
+const lineSeries: Highcharts.SeriesLineOptions[] = [
+  {
+    name: "Installation",
+    data: [43934, 52503, 57177, 69658, 97031, 119931, 137133, 154175],
+    type: "line",
+  },
+  {
+    name: "Manufacturing",
+    data: [24916, 24064, 29742, 29851, 32490, 30282, 38121, 40434],
+    type: "line",
+  },
+  {
+    name: "Sales & Distribution",
+    data: [11744, 17722, 16005, 19771, 20185, 24377, 32147, 39387],
+    type: "line",
+  },
+  {
+    name: "Project Development",
+    data: [null, null, 7988, 12169, 15112, 22452, 34400, 34227],
+    type: "line",
+  },
+  {
+    name: "Other",
+    data: [12908, 5948, 8105, 11248, 8989, 11816, 18274, 18111],
+    type: "line",
+  },
+];
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: "Components/ChartProvider",
+};
+
+export const Default: StoryFn = () => {
+  return (
+    <ChartProvider highchartsOptions={{ chart: { type: "line" }, series: lineSeries }}>
+      <BaseChart />
+    </ChartProvider>
+  );
+};

packages/paste-core/components/chart-provider/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/",
+  },
+  "include": [
+    "src/**/*",
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}