LG-5588 more chart customization points (#3274)

* feat: more chart customization points

* docs: add changelog

* feat: apply review feedbacks

* feat: move common x/y axis properties into a separate file

* fix: lint errors

* fix: correct props dependency

* fixup! fix: lint errors

* feat: process review feedback

* feat: apply Stephen's feedback

* types: export bar-hover-behavior type

* more PR review feedback

* fix export issue

Author: nima-taheri-mongodb

.changeset/rotten-parrots-stare.md

@@ -0,0 +1,12 @@
+---
+'@lg-charts/core': minor
+---
+
+- ChartTooltip:
+  - Added `axisPointer` prop supporting 'line', 'shadow', and 'none' options
+  - Added `className` prop for custom styling
+  - Bug Fix: renders correctly for values like 0 and empty strings by only checking for null or undefined, not all falsy values
+- Bar: `hoverBehavior` prop now accepts 'dim-others' and 'none' options to control hover focus behavior
+- XAxis/YAxis: Introduced a new `category` axis type for discrete/categorical datasets (such as for X axes in bar charts).
+  - It uses a dedicated axis type definition and a `labels` prop for specifying category names.
+  - Existing continuous axis types (`'log'`, `'time'`, `'value'`) remain unchanged, continuing to support `min`, `max`, and `formatter` for customization.

charts/core/src/Axis/Axis.ts

@@ -0,0 +1,68 @@
+import { CartesianAxisOption } from 'echarts/types/src/coord/cartesian/AxisModel.js';
+
+import { Theme } from '@leafygreen-ui/lib';
+import {
+  color,
+  fontFamilies,
+  fontWeights,
+  InteractionState,
+  spacing,
+  Variant,
+} from '@leafygreen-ui/tokens';
+
+import { type AxisProps } from './Axis.types';
+
+export const getAxisOptions = (
+  theme: Theme,
+  props: AxisProps,
+): CartesianAxisOption => {
+  const { label, type } = props;
+
+  return {
+    type,
+    ...(type === 'category'
+      ? {
+          data: props.labels,
+        }
+      : {
+          min: props.min,
+          max: props.max,
+        }),
+    axisLine: {
+      show: true,
+      lineStyle: {
+        color: color[theme].border[Variant.Secondary][InteractionState.Default],
+        width: 1,
+      },
+    },
+    axisLabel: {
+      show: true,
+      fontFamily: fontFamilies.default,
+      fontWeight: fontWeights.medium,
+      fontSize: 11,
+      lineHeight: spacing[400],
+      color: color[theme].text[Variant.Secondary][InteractionState.Default],
+      ...(type === 'category' ? undefined : { formatter: props.formatter }),
+    },
+    axisTick: {
+      show: false,
+    },
+    name: label,
+    nameLocation: 'middle',
+    nameTextStyle: {
+      fontFamily: fontFamilies.default,
+      fontWeight: fontWeights.medium,
+      fontSize: 11,
+      color: color[theme].text[Variant.Secondary][InteractionState.Default],
+    },
+  };
+};
+
+export const unsetAxisOptions = {
+  axisLine: {
+    show: false,
+  },
+  axisLabel: {
+    show: false,
+  },
+};

charts/core/src/Axis/Axis.types.ts

@@ -0,0 +1,74 @@
+import type { AxisLabelValueFormatter } from '../Echart/Echart.types';
+
+/**
+ * Note: choosing this axis type implicates that the charting library is free to automatically interpolate axis labels and their positions
+ * which might not exactly align to each provided data point.
+ */
+const ContinuousAxisTypes = {
+  Log: 'log',
+  Time: 'time',
+  Value: 'value',
+} as const;
+
+type ContinuousAxisTypes =
+  (typeof ContinuousAxisTypes)[keyof typeof ContinuousAxisTypes];
+
+const DiscreteAxisTypes = {
+  Category: 'category',
+} as const;
+
+type DiscreteAxisTypes =
+  (typeof DiscreteAxisTypes)[keyof typeof DiscreteAxisTypes];
+
+export const AxisType = {
+  ...ContinuousAxisTypes,
+  ...DiscreteAxisTypes,
+} as const;
+
+export type AxisType = (typeof AxisType)[keyof typeof AxisType];
+
+interface AxisPropsBase {
+  /**
+   * Label name of the axis.
+   */
+  label?: string;
+  /**
+   * Type of the axis.
+   */
+  type: AxisType;
+}
+
+export interface ContinuousAxisProps extends AxisPropsBase {
+  type: ContinuousAxisTypes;
+
+  /**
+   *
+   * Formatter of axis label, which supports string template and callback function.
+   *
+   * ```ts
+   * formatter: (value, index) => `${value}GB`
+   * ```
+   */
+  formatter?: AxisLabelValueFormatter | string;
+
+  /**
+   * Minimum value of the axis.
+   */
+  min?: number;
+
+  /**
+   * Maximum value of the axis.
+   */
+  max?: number;
+}
+
+export interface DiscreteAxisProps extends AxisPropsBase {
+  type: DiscreteAxisTypes;
+
+  /**
+   * Labels of the data points on the axis.
+   */
+  labels?: Array<string>;
+}
+
+export type AxisProps = ContinuousAxisProps | DiscreteAxisProps;

charts/core/src/Axis/XAxis.tsx

@@ -0,0 +1,79 @@
+import { useEffect } from 'react';
+import merge from 'lodash/merge';
+
+import { useObjectDependency } from '@leafygreen-ui/hooks';
+import { useDarkMode } from '@leafygreen-ui/leafygreen-provider';
+import { Theme } from '@leafygreen-ui/lib';
+import { spacing } from '@leafygreen-ui/tokens';
+
+import { useChartContext } from '../ChartContext';
+import { type EChartOptions } from '../Echart';
+
+import { getAxisOptions, unsetAxisOptions } from './Axis';
+import { XAxisProps } from './XAxis.types';
+
+const getXAxisOptions = (
+  theme: Theme,
+  props: XAxisProps,
+): Omit<EChartOptions, 'series'> => {
+  const axisOptions = merge(getAxisOptions(theme, props), {
+    axisLabel: {
+      align: 'center',
+      margin: spacing[400],
+    },
+    nameTextStyle: {
+      lineHeight: spacing[400],
+      padding: [spacing[200], 0, 0, 0],
+    },
+    nameGap: spacing[1000],
+  });
+
+  return {
+    xAxis: axisOptions,
+    grid: {
+      bottom: props.label
+        ? spacing[1200] // Pushes out to make room for the label
+        : spacing[400], // Default bottom spacing
+    },
+  };
+};
+
+/**
+ * React component that can render an x-axis on a parent chart.
+ *
+ * This is done by updating the parent chart's canvas configuration received via context.
+ *
+ * ```
+ * <Chart>
+ *   <XAxis
+ *     type="time",
+ *     label="My X-Axis Data",
+ *     formatter="{value}GB"
+ *   />
+ * </Chart>
+ */
+export function XAxis(props: XAxisProps) {
+  const {
+    chart: { ready, updateOptions },
+  } = useChartContext();
+  const { theme } = useDarkMode();
+  const propsDep = useObjectDependency(props);
+
+  useEffect(() => {
+    if (!ready) return;
+
+    updateOptions(getXAxisOptions(theme, propsDep));
+
+    return () => {
+      /**
+       * Hides the axis when the component is unmounted.
+       */
+      updateOptions({
+        xAxis: { ...unsetAxisOptions },
+        grid: { bottom: spacing[400] }, // Reset the grid bottom spacing
+      });
+    };
+  }, [ready, theme, updateOptions, propsDep]);
+
+  return null;
+}

charts/core/src/Axis/XAxis.types.ts

@@ -0,0 +1,6 @@
+import { AxisProps, AxisType } from './Axis.types';
+
+export const XAxisType = AxisType;
+type XAxisType = (typeof XAxisType)[keyof typeof XAxisType];
+
+export type XAxisProps = AxisProps;

charts/core/src/Axis/YAxis.tsx

@@ -0,0 +1,78 @@
+import { useEffect } from 'react';
+import merge from 'lodash/merge';
+
+import { useObjectDependency } from '@leafygreen-ui/hooks';
+import { useDarkMode } from '@leafygreen-ui/leafygreen-provider';
+import { Theme } from '@leafygreen-ui/lib';
+import { spacing } from '@leafygreen-ui/tokens';
+
+import { useChartContext } from '../ChartContext';
+import { type EChartOptions } from '../Echart';
+
+import { getAxisOptions, unsetAxisOptions } from './Axis';
+import { YAxisProps } from './YAxis.types';
+
+const getYAxisOptions = (
+  theme: Theme,
+  props: YAxisProps,
+): Omit<EChartOptions, 'series'> => {
+  const axisOptions = merge(getAxisOptions(theme, props), {
+    axisLabel: {
+      align: 'right',
+      margin: spacing[200],
+    },
+    nameTextStyle: {
+      padding: [0, 0, spacing[800], 0],
+    },
+    nameGap: spacing[900],
+  });
+
+  return {
+    yAxis: axisOptions,
+    grid: {
+      left: props.label
+        ? spacing[1200] // Pushes out to make room for the label
+        : spacing[300], // Default left spacing
+    },
+  };
+};
+
+/**
+ * React component that can render an y-axis on a parent chart.
+ *
+ * This is done by updating the parent chart's canvas configuration received via context.
+ *
+ * ```
+ * <Chart>
+ *   <YAxis
+ *     type="value",
+ *     label="My Y-Axis Data",
+ *     formatter="{value}GB"
+ *   />
+ * </Chart>
+ */
+export function YAxis(props: YAxisProps) {
+  const {
+    chart: { ready, updateOptions },
+  } = useChartContext();
+  const { theme } = useDarkMode();
+  const propsDep = useObjectDependency(props);
+
+  useEffect(() => {
+    if (!ready) return;
+
+    updateOptions(getYAxisOptions(theme, propsDep));
+
+    return () => {
+      /**
+       * Hides the axis when the component is unmounted.
+       */
+      updateOptions({
+        yAxis: { ...unsetAxisOptions },
+        grid: { left: spacing[300] }, // Reset the grid left spacing
+      });
+    };
+  }, [ready, theme, updateOptions, propsDep]);
+
+  return null;
+}

charts/core/src/Axis/YAxis.types.ts

@@ -0,0 +1,6 @@
+import { AxisProps, AxisType } from './Axis.types';
+
+export const YAxisType = AxisType;
+type YAxisType = (typeof YAxisType)[keyof typeof YAxisType];
+
+export type YAxisProps = AxisProps;

charts/core/src/Axis/index.ts

@@ -0,0 +1,10 @@
+export type {
+  AxisProps,
+  AxisType,
+  ContinuousAxisProps,
+  DiscreteAxisProps,
+} from './Axis.types';
+export { XAxis } from './XAxis';
+export type { XAxisProps, XAxisType } from './XAxis.types';
+export { YAxis } from './YAxis';
+export type { YAxisProps, YAxisType } from './YAxis.types';