LG-4659: Replace axes unit prop with formatter (#2536)

* Replace `unit` with `formatter` * Update README * Changeset * Add formatting to time in storybook * Remove documented support for non-callback formatter types * Update README example
mongodb · Nov 4, 2024 · 728fa7a · 728fa7a
1 parent aee5093
commit 728fa7a
Show file tree

Hide file tree

Showing 7 changed files with 64 additions and 55 deletions.
diff --git a/.changeset/silly-jars-cheat.md b/.changeset/silly-jars-cheat.md
@@ -0,0 +1,5 @@
+---
+'@lg-charts/core': minor
+---
+
+Replaces `unit` prop of `XAxis` and `YAxis` with `formatter` prop
diff --git a/charts/core/README.md b/charts/core/README.md
@@ -26,7 +26,7 @@ import { Chart, Line, Grid, XAxis, YAxis } from '@lg-charts/core';
 <Chart>
   <Grid vertical={false}>
   <XAxis type="time" />
-  <YAxis type="value" unit="GB" />
+  <YAxis type="value" formatter={(value) => `${value}GB`} />
   <Line
     name="Series 1"
     data={[
@@ -92,20 +92,20 @@ Renders an x-axis.
 
 #### Props
 
-| Name                 | Description                                                                                                                                                                                                                                                                           | Type                                     | Default |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------- |
-| `type`               | Type of axis.                                                                                                                                                                                                                                                                         | 'category' \| 'value' \| 'time' \| 'log' |         |
-| `label` _(optional)_ | Label name to be rendered on the axis.                                                                                                                                                                                                                                                | string                                   |         |
-| `unit` _(optional)_  | String that will be appended to the values of the axis. Only applies if `type` of `value`. _Note: this unit will not impact the data. E.g. if data is given in MB and the units are set to "GB", the component won’t convert these values. Conversion of data is up to the consumer._ | string                                   |         |
+| Name                     | Description                                   | Type                                     | Default |
+| ------------------------ | --------------------------------------------- | ---------------------------------------- | ------- |
+| `type`                   | Type of axis.                                 | 'category' \| 'value' \| 'time' \| 'log' |         |
+| `label` _(optional)_     | Label name to be rendered on the axis.        | string                                   |         |
+| `formatter` _(optional)_ | Callback function for formatting tick values. | (value: string, index: number) => string |         |
 
 ### `YAxis`
 
 Renders a y-axis.
 
 #### Props
 
-| Name                 | Description                                                                                                                                                                                                                                                                           | Type                                     | Default |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------- |
-| `type`               | Type of axis.                                                                                                                                                                                                                                                                         | 'category' \| 'value' \| 'time' \| 'log' |         |
-| `label` _(optional)_ | Label name to be rendered on the axis.                                                                                                                                                                                                                                                | string                                   |         |
-| `unit` _(optional)_  | String that will be appended to the values of the axis. Only applies if `type` of `value`. _Note: this unit will not impact the data. E.g. if data is given in MB and the units are set to "GB", the component won’t convert these values. Conversion of data is up to the consumer._ | string                                   |         |
+| Name                     | Description                                   | Type                                     | Default |
+| ------------------------ | --------------------------------------------- | ---------------------------------------- | ------- |
+| `type`                   | Type of axis.                                 | 'category' \| 'value' \| 'time' \| 'log' |         |
+| `label` _(optional)_     | Label name to be rendered on the axis.        | string                                   |         |
+| `formatter` _(optional)_ | Callback function for formatting tick values. | (value: string, index: number) => string |         |
diff --git a/charts/core/src/XAxis/XAxis.tsx b/charts/core/src/XAxis/XAxis.tsx
@@ -14,13 +14,13 @@ import {
 import { ChartOptions } from '../Chart/Chart.types';
 import { useChartContext } from '../ChartContext';
 
-import { XAxisProps, XAxisType } from './XAxis.types';
+import { XAxisProps } from './XAxis.types';
 
 const getOptions = ({
   theme,
   type,
   label,
-  unit,
+  formatter,
 }: XAxisProps & { theme: Theme }): Partial<ChartOptions> => {
   const options: Partial<ChartOptions> = {
     xAxis: {
@@ -42,10 +42,7 @@ const getOptions = ({
         color: color[theme].text[Variant.Secondary][InteractionState.Default],
         align: 'center',
         margin: spacing[400],
-        formatter:
-          unit && type === XAxisType.Value
-            ? (value: string) => `${value}${unit}`
-            : undefined,
+        formatter,
       },
       axisTick: {
         show: false,
@@ -96,16 +93,16 @@ const unsetAxisOptions = {
  *   <XAxis
  *     type="time",
  *     label="My X-Axis Data",
- *     unit="GB"
+ *     formatter="{value}GB"
  *   />
  * </Chart>
  */
-export function XAxis({ type, label, unit }: XAxisProps) {
+export function XAxis({ type, label, formatter }: XAxisProps) {
   const { updateChartOptions } = useChartContext();
   const { theme } = useDarkMode();
 
   useEffect(() => {
-    updateChartOptions(getOptions({ type, label, unit, theme }));
+    updateChartOptions(getOptions({ type, label, formatter, theme }));
 
     return () => {
       /**
@@ -115,7 +112,7 @@ export function XAxis({ type, label, unit }: XAxisProps) {
         xAxis: unsetAxisOptions,
       });
     };
-  }, [type, label, unit, theme, updateChartOptions]);
+  }, [type, label, formatter, theme, updateChartOptions]);
 
   return null;
 }
diff --git a/charts/core/src/XAxis/XAxis.types.ts b/charts/core/src/XAxis/XAxis.types.ts
@@ -18,7 +18,12 @@ export interface XAxisProps {
   label?: string;
 
   /**
-   * Unit of the axis to be rendered with value.
+   *
+   * Formatter of axis label, which supports string template and callback function.
+   *
+   * ```ts
+   * formatter: (value, index) => `${value}GB`
+   * ```
    */
-  unit?: string;
+  formatter?: (value: string, index: number) => string;
 }
diff --git a/charts/core/src/YAxis/YAxis.tsx b/charts/core/src/YAxis/YAxis.tsx
@@ -14,13 +14,13 @@ import {
 import { ChartOptions } from '../Chart/Chart.types';
 import { useChartContext } from '../ChartContext';
 
-import { YAxisProps, YAxisType } from './YAxis.types';
+import { YAxisProps } from './YAxis.types';
 
 const getOptions = ({
   theme,
   type,
   label,
-  unit,
+  formatter,
 }: YAxisProps & { theme: Theme }): Partial<ChartOptions> => {
   const options: Partial<ChartOptions> = {
     yAxis: {
@@ -42,10 +42,7 @@ const getOptions = ({
         color: color[theme].text[Variant.Secondary][InteractionState.Default],
         align: 'right',
         margin: spacing[200],
-        formatter:
-          unit && type === YAxisType.Value
-            ? (value: string) => `${value}${unit}`
-            : undefined,
+        formatter,
       },
       axisTick: {
         show: false,
@@ -95,16 +92,16 @@ const unsetAxisOptions = {
  *   <YAxis
  *     type="value",
  *     label="My Y-Axis Data",
- *     unit="GB"
+ *     formatter="{value}GB"
  *   />
  * </Chart>
  */
-export function YAxis({ type, label, unit }: YAxisProps) {
+export function YAxis({ type, label, formatter }: YAxisProps) {
   const { updateChartOptions } = useChartContext();
   const { theme } = useDarkMode();
 
   useEffect(() => {
-    updateChartOptions(getOptions({ type, label, unit, theme }));
+    updateChartOptions(getOptions({ type, label, formatter, theme }));
 
     return () => {
       /**
@@ -114,7 +111,7 @@ export function YAxis({ type, label, unit }: YAxisProps) {
         yAxis: unsetAxisOptions,
       });
     };
-  }, [type, label, unit, theme, updateChartOptions]);
+  }, [type, label, formatter, theme, updateChartOptions]);
 
   return null;
 }
diff --git a/charts/core/src/YAxis/YAxis.types.ts b/charts/core/src/YAxis/YAxis.types.ts
@@ -19,7 +19,15 @@ export interface YAxisProps {
   label?: string;
 
   /**
-   * Unit of the axis to be rendered with value. Only applies if `type` of `value`.
+   *
+   * Formatter of axis label, which supports string template and callback function.
+   *
+   * ```ts
+   * // Use callback.
+   * formatter: function (value, index) {
+   *   return value + 'kg';
+   *}
+   * ```
    */
-  unit?: string;
+  formatter?: (value: string, index: number) => string;
 }
diff --git a/charts/core/src/core.stories.tsx b/charts/core/src/core.stories.tsx
@@ -43,12 +43,11 @@ export default {
         category: 'XAxis',
       },
     },
-    xAxisUnit: {
-      control: 'text',
-      description: 'X-axis units',
-      name: 'Unit',
+    xAxisFormatter: {
+      description: 'X-axis formatter',
+      name: 'Formatter',
       table: {
-        category: 'XAxis',
+        disable: true,
       },
     },
     xAxisLabel: {
@@ -68,12 +67,11 @@ export default {
         category: 'YAxis',
       },
     },
-    yAxisUnit: {
-      control: 'text',
-      description: 'Y-axis units',
-      name: 'Unit',
+    yAxisFormatter: {
+      description: 'Y-axis formatter',
+      name: 'Formatter',
       table: {
-        category: 'YAxis',
+        disable: true,
       },
     },
     yAxisLabel: {
@@ -103,10 +101,10 @@ interface StoryChartProps {
   horizontalGridLines: boolean;
   xAxisType: XAxisProps['type'];
   yAxisType: YAxisProps['type'];
-  xAxisUnit: string;
-  yAxisUnit: string;
-  xAxisLabel: string;
-  yAxisLabel: string;
+  xAxisFormatter: XAxisProps['formatter'];
+  yAxisFormatter: XAxisProps['formatter'];
+  xAxisLabel: XAxisProps['label'];
+  yAxisLabel: YAxisProps['label'];
 }
 
 const Template: React.FC<StoryChartProps> = props => {
@@ -115,18 +113,18 @@ const Template: React.FC<StoryChartProps> = props => {
     verticalGridLines,
     horizontalGridLines,
     xAxisType,
-    xAxisUnit,
+    xAxisFormatter,
     yAxisType,
-    yAxisUnit,
+    yAxisFormatter,
     xAxisLabel,
     yAxisLabel,
   } = props;
 
   return (
     <Chart {...props}>
       <Grid vertical={verticalGridLines} horizontal={horizontalGridLines} />
-      <XAxis type={xAxisType} unit={xAxisUnit} label={xAxisLabel} />
-      <YAxis type={yAxisType} unit={yAxisUnit} label={yAxisLabel} />
+      <XAxis type={xAxisType} formatter={xAxisFormatter} label={xAxisLabel} />
+      <YAxis type={yAxisType} formatter={yAxisFormatter} label={yAxisLabel} />
       {data.map(({ name, data }) => (
         <Line name={name} data={data} key={name} />
       ))}
@@ -141,6 +139,5 @@ LiveExample.args = {
   verticalGridLines: false,
   xAxisType: 'time',
   yAxisType: 'value',
-  xAxisUnit: '',
-  yAxisUnit: 'GB',
+  yAxisFormatter: value => `${value}GB`,
 };