@trackunit/react-chart-components 2.1.43-alpha-6a85feaada3.0 → 2.1.43

package/index.cjs.js

@@ -1,14 +1,14 @@
 'use strict';
 
 var jsxRuntime = require('react/jsx-runtime');
-var reactComponents = require('@trackunit/react-components');
 var cssClassVarianceUtilities = require('@trackunit/css-class-variance-utilities');
-var sharedUtils = require('@trackunit/shared-utils');
-var echarts = require('echarts');
-var react = require('react');
-var uiDesignTokens = require('@trackunit/ui-design-tokens');
 var dateAndTimeUtils = require('@trackunit/date-and-time-utils');
 var reactDateAndTimeHooks = require('@trackunit/react-date-and-time-hooks');
+var uiDesignTokens = require('@trackunit/ui-design-tokens');
+var react = require('react');
+var reactComponents = require('@trackunit/react-components');
+var sharedUtils = require('@trackunit/shared-utils');
+var echarts = require('echarts');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -303,6 +303,241 @@ const useChartColor = () => {
     }), [chartColor, chartColorArray, chartStatusColor]);
 };
 
+/**
+ * Locale-aware number formatting helpers for charts. Mirrors `useChartColor`:
+ * a hook that returns memoized formatting functions so chart consumers share one
+ * consistent compact-number style instead of hand-rolling `>= 1000 → k` logic.
+ *
+ * @returns {{ formatCompact: (value: number) => string }} An object exposing
+ * `formatCompact`, a locale-aware compact formatter (e.g. `40000 → "40K"`, `40_000_000 → "40M"`).
+ * @example Abbreviate a y-axis value
+ * ```tsx
+ * const { formatCompact } = useChartNumberFormat();
+ * formatCompact(40000); // "40K"
+ * ```
+ */
+const useChartNumberFormat = () => {
+    const locale = reactDateAndTimeHooks.useLocale();
+    const formatCompact = react.useCallback((value) => new Intl.NumberFormat(locale, { notation: "compact", maximumFractionDigits: 1 }).format(value), [locale]);
+    return react.useMemo(() => ({ formatCompact }), [formatCompact]);
+};
+
+const DEFAULT_DATE_FORMAT = { selectFormat: "dateOnly", dateFormat: "medium" };
+const DEFAULT_ROTATE_LABELS = 45;
+const isDateData = (data) => !!data && "date" in data;
+const isEChartsTooltipParam = (param) => typeof param === "object" &&
+    param !== null &&
+    "seriesName" in param &&
+    typeof param.seriesName === "string" &&
+    "seriesIndex" in param &&
+    typeof param.seriesIndex === "number" &&
+    "dataIndex" in param &&
+    typeof param.dataIndex === "number" &&
+    "color" in param &&
+    typeof param.color === "string" &&
+    "marker" in param &&
+    typeof param.marker === "string";
+/**
+ * Create a BarChart with automatic legends and formatting. Built on top of the Chart component
+ * with sensible defaults for displaying categorical or time-series data.
+ *
+ * All customization props are optional and default to the component's original rendering, so
+ * existing usages are unaffected.
+ *
+ * ### When to use
+ * - To compare values across categories
+ * - To show trends over time with discrete intervals
+ * - When you need multiple series displayed side by side
+ *
+ * @example Bar chart with date-based data
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const UtilizationChart = () => (
+ *   <BarChart
+ *     series={{
+ *       name: "Utilization",
+ *       data: [
+ *         { date: "2024-01-01", value: 85 },
+ *         { date: "2024-01-02", value: 72 },
+ *         { date: "2024-01-03", value: 91 },
+ *       ],
+ *     }}
+ *     units="%"
+ *     onClick={(event) => console.log("Clicked bar:", event.data)}
+ *   />
+ * );
+ * ```
+ * @example Multi-series bar chart with data zoom
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const ComparisonChart = () => (
+ *   <BarChart
+ *     series={[
+ *       { name: "2023", color: "#3b82f6", data: [{ key: "Q1", value: 100 }, { key: "Q2", value: 120 }] },
+ *       { name: "2024", color: "#10b981", data: [{ key: "Q1", value: 130 }, { key: "Q2", value: 145 }] },
+ *     ]}
+ *     units="units"
+ *     showDataZoom={true}
+ *   />
+ * );
+ * ```
+ * @example Abbreviated y-axis, horizontal x-axis labels and a hidden legend
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const EmissionsChart = () => (
+ *   <BarChart
+ *     series={{ name: "Emissions", data: [{ key: "Excavator", value: 40000, color: "#3b82f6" }] }}
+ *     units="t"
+ *     yAxis={{ abbreviate: true }}
+ *     xAxis={{ rotateLabels: 0, formatLabel: (value) => value.slice(0, 10) }}
+ *     showLegend={false}
+ *   />
+ * );
+ * ```
+ * @example Custom tooltip from the typed payload
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const TrendChart = () => (
+ *   <BarChart
+ *     series={{ name: "Emissions", data: [{ date: "2024-01-01", value: 120 }] }}
+ *     tooltip={{
+ *       trigger: "axis",
+ *       formatter: ({ axisValue, entries }) =>
+ *         `${axisValue}<br/>${entries.map((e) => `${e.marker} ${e.seriesName}: ${e.value ?? 0}`).join("<br/>")}`,
+ *     }}
+ *   />
+ * );
+ * ```
+ * @param {BarChartProps} props - The props for the Chart component
+ * @returns {ReactElement} Chart component
+ */
+const BarChart = ({ series, loading = false, onClick, className, style, "data-testid": dataTestId, units, showDataZoom = false, xAxis, yAxis, tooltip, showLegend = true, ref, }) => {
+    const { formatDate } = reactDateAndTimeHooks.useDateAndTime();
+    const { chartColor } = useChartColor();
+    const { formatCompact } = useChartNumberFormat();
+    const seriesData = react.useMemo(() => {
+        const seriesAsArray = Array.isArray(series) ? series : series !== undefined ? [series] : [];
+        return seriesAsArray.map((s, i) => ({
+            ...s,
+            color: s.color || chartColor(i),
+            type: "bar",
+            cursor: "arrow",
+            barGap: "0",
+            data: s.data.map(d => ({
+                ...d,
+                itemStyle: d.color ? { color: d.color } : undefined,
+            })),
+        }));
+    }, [series, chartColor]);
+    const yAxisLabelFormatter = react.useMemo(() => {
+        if (yAxis?.formatLabel) {
+            return yAxis.formatLabel;
+        }
+        if (yAxis?.abbreviate) {
+            return (value) => formatCompact(value);
+        }
+        return undefined;
+    }, [yAxis, formatCompact]);
+    const buildTooltipParams = react.useCallback((rawParams) => {
+        const params = Array.isArray(rawParams) ? rawParams : [rawParams];
+        const validParams = params.filter(isEChartsTooltipParam);
+        const firstParam = validParams[0];
+        const axisValueRaw = firstParam?.axisValue ?? firstParam?.name;
+        const axisValue = axisValueRaw === undefined ? "" : String(axisValueRaw);
+        const entries = validParams.map(param => {
+            const dataItem = seriesData[param.seriesIndex]?.data[param.dataIndex];
+            return {
+                seriesName: param.seriesName,
+                value: dataItem?.value,
+                color: param.color,
+                marker: param.marker,
+                dataIndex: param.dataIndex,
+                original: dataItem?.original,
+            };
+        });
+        return { axisValue, entries };
+    }, [seriesData]);
+    const tooltipTrigger = tooltip?.trigger ?? "item";
+    const tooltipFormatter = tooltip?.formatter;
+    const tooltipValueFormatter = tooltip?.formatValue;
+    return (jsxRuntime.jsxs("div", { className: cvaChartRoot$1({ className }), "data-testid": dataTestId, ref: ref, style: style, children: [showLegend ? (jsxRuntime.jsx("div", { className: "flex-0 flex flex-row gap-2 place-self-end pr-8", "data-testid": "legend", children: seriesData.map((item, index) => (jsxRuntime.jsx(LegendItem, { color: item.color || chartColor(index), "data-testid": `legend-${item.name}`, label: item.name }, item.name))) })) : null, jsxRuntime.jsx("div", { className: "flex w-full flex-1", children: jsxRuntime.jsx(Chart, { "data-testid": "bar-chart", onClick: onClick
+                        ? (e) => {
+                            onClick(e);
+                        }
+                        : undefined, options: {
+                        tooltip: {
+                            trigger: tooltipTrigger,
+                            confine: true,
+                            axisPointer: tooltipTrigger === "axis" ? { type: "shadow" } : undefined,
+                            formatter: tooltipFormatter
+                                ? (rawParams) => tooltipFormatter(buildTooltipParams(rawParams))
+                                : undefined,
+                            valueFormatter: tooltipFormatter
+                                ? undefined
+                                : value => tooltipValueFormatter && typeof value === "number"
+                                    ? tooltipValueFormatter(value)
+                                    : `${value} ${units ?? ""}`,
+                        },
+                        grid: {
+                            left: "2%",
+                            right: "2%",
+                            bottom: "10%",
+                            top: "10%",
+                            containLabel: true,
+                        },
+                        xAxis: [
+                            {
+                                type: "category",
+                                axisLabel: {
+                                    formatter: (value, index) => {
+                                        if (xAxis?.formatLabel) {
+                                            return xAxis.formatLabel(value, index);
+                                        }
+                                        if (isDateData(seriesData[0]?.data[0])) {
+                                            const date = formatDate(dateAndTimeUtils.toDateUtil(value), xAxis?.dateFormat ?? DEFAULT_DATE_FORMAT);
+                                            return date.replace(",", ",\n");
+                                        }
+                                        return value;
+                                    },
+                                    fontSize: 10,
+                                    fontFamily: uiDesignTokens.fontFamily,
+                                    rotate: xAxis?.rotateLabels ?? DEFAULT_ROTATE_LABELS,
+                                    overflow: "truncate",
+                                },
+                                data: seriesData[0]?.data.map(data => (isDateData(data) ? data.date : data.key)),
+                            },
+                        ],
+                        dataZoom: showDataZoom
+                            ? [
+                                {
+                                    type: "slider",
+                                    id: "insideX",
+                                    xAxisIndex: 0,
+                                    startValue: 0,
+                                    endValue: (seriesData[0]?.data.length ?? 0) > 10 ? 10 : (seriesData[0]?.data.length ?? 0),
+                                    showDetail: false,
+                                },
+                            ]
+                            : [],
+                        yAxis: [
+                            {
+                                type: "value",
+                                axisLabel: {
+                                    fontSize: 10,
+                                    fontFamily: uiDesignTokens.fontFamily,
+                                    formatter: yAxisLabelFormatter,
+                                },
+                            },
+                        ],
+                        series: seriesData,
+                    }, showLoading: loading, style: { height: "100%", minHeight: "150px", width: "100%" } }) })] }));
+};
+const cvaChartRoot$1 = cssClassVarianceUtilities.cvaMerge(["flex", "flex-col", "items-center", "h-full"]);
+
 /**
  * Limits the data set to the given limit.
  * If the data set is larger than the limit, the data set is limited to the limit and the rest of the data is added to the "Others" group.
@@ -508,9 +743,9 @@ const DonutChart = ({ data, size = "full", loading = false, onClick, className,
     if (loading) {
         return jsxRuntime.jsx(reactComponents.Spinner, { centering: "centered", "data-testid": dataTestId ? `${dataTestId}-loading` : "donut-chart-loading" });
     }
-    return (jsxRuntime.jsxs("div", { className: cvaChartRoot$1({ className }), "data-testid": dataTestId, ref: mergedRef, style: style, children: [jsxRuntime.jsx("div", { className: cvaChartContainer(), children: jsxRuntime.jsx(Chart, { className: cvaChart({ size }), "data-testid": dataTestId ? `chart-${dataTestId}` : undefined, onChartReady: handleChartReady, onClick: handleChartClick, onEvents: handleChartEvents, options: chartOptions, style: { width: "100%", height: "100%" } }) }), size === "full" && (jsxRuntime.jsx("div", { className: cvaLegend(), "data-testid": "legend", children: limitedData.map((item, index) => (jsxRuntime.jsx(LegendItem, { className: "p-1.5 py-0.5", color: item.color ?? chartColor(index), count: item.value, "data-testid": `legend-${item.id}`, disabled: (item.value ?? 0) === 0, hideValue: hideLegendValues, label: item.name, onClick: onClick ? () => onClick(item) : undefined, onMouseEnter: () => handleLegendMouseEnter(item), onMouseLeave: handleLegendMouseLeave, selected: item.selected, unit: unit }, item.id))) }))] }));
+    return (jsxRuntime.jsxs("div", { className: cvaChartRoot({ className }), "data-testid": dataTestId, ref: mergedRef, style: style, children: [jsxRuntime.jsx("div", { className: cvaChartContainer(), children: jsxRuntime.jsx(Chart, { className: cvaChart({ size }), "data-testid": dataTestId ? `chart-${dataTestId}` : undefined, onChartReady: handleChartReady, onClick: handleChartClick, onEvents: handleChartEvents, options: chartOptions, style: { width: "100%", height: "100%" } }) }), size === "full" && (jsxRuntime.jsx("div", { className: cvaLegend(), "data-testid": "legend", children: limitedData.map((item, index) => (jsxRuntime.jsx(LegendItem, { className: "p-1.5 py-0.5", color: item.color ?? chartColor(index), count: item.value, "data-testid": `legend-${item.id}`, disabled: (item.value ?? 0) === 0, hideValue: hideLegendValues, label: item.name, onClick: onClick ? () => onClick(item) : undefined, onMouseEnter: () => handleLegendMouseEnter(item), onMouseLeave: handleLegendMouseLeave, selected: item.selected, unit: unit }, item.id))) }))] }));
 };
-const cvaChartRoot$1 = cssClassVarianceUtilities.cvaMerge([
+const cvaChartRoot = cssClassVarianceUtilities.cvaMerge([
     "flex",
     "w-full",
     "h-full",
@@ -533,139 +768,10 @@ const cvaChart = cssClassVarianceUtilities.cvaMerge(["flex-0", "max-w-[200px]",
 });
 const cvaLegend = cssClassVarianceUtilities.cvaMerge(["flex", "overflow-auto", "justify-start", "flex-col", "flex-1"]);
 
-/**
- * Create a BarChart with automatic legends and formatting. Built on top of the Chart component
- * with sensible defaults for displaying categorical or time-series data.
- *
- * ### When to use
- * - To compare values across categories
- * - To show trends over time with discrete intervals
- * - When you need multiple series displayed side by side
- *
- * @example Bar chart with date-based data
- * ```tsx
- * import { BarChart } from "@trackunit/react-chart-components";
- *
- * const UtilizationChart = () => (
- *   <BarChart
- *     series={{
- *       name: "Utilization",
- *       data: [
- *         { date: "2024-01-01", value: 85 },
- *         { date: "2024-01-02", value: 72 },
- *         { date: "2024-01-03", value: 91 },
- *       ],
- *     }}
- *     units="%"
- *     onClick={(event) => console.log("Clicked bar:", event.data)}
- *   />
- * );
- * ```
- * @example Multi-series bar chart with data zoom
- * ```tsx
- * import { BarChart } from "@trackunit/react-chart-components";
- *
- * const ComparisonChart = () => (
- *   <BarChart
- *     series={[
- *       { name: "2023", color: "#3b82f6", data: [{ key: "Q1", value: 100 }, { key: "Q2", value: 120 }] },
- *       { name: "2024", color: "#10b981", data: [{ key: "Q1", value: 130 }, { key: "Q2", value: 145 }] },
- *     ]}
- *     units="units"
- *     showDataZoom={true}
- *   />
- * );
- * ```
- * @param {BarChartProps} props - The props for the Chart component
- * @returns {ReactElement} Chart component
- */
-const BarChart = ({ series, loading = false, onClick, className, style, "data-testid": dataTestId, units, showDataZoom = false, ref, }) => {
-    const { formatDate } = reactDateAndTimeHooks.useDateAndTime();
-    const { chartColor } = useChartColor();
-    const seriesData = react.useMemo(() => {
-        const seriesAsArray = Array.isArray(series) ? series : series !== undefined ? [series] : [];
-        return seriesAsArray.map((s, i) => ({
-            ...s,
-            color: s.color || chartColor(i),
-            type: "bar",
-            cursor: "arrow",
-            barGap: "0",
-            data: s.data.map(d => ({
-                ...d,
-            })),
-        }));
-    }, [series, chartColor]);
-    const isDateData = (data) => !!data && "date" in data;
-    return (jsxRuntime.jsxs("div", { className: cvaChartRoot({ className }), "data-testid": dataTestId, ref: ref, style: style, children: [jsxRuntime.jsx("div", { className: "flex-0 flex flex-row gap-2 place-self-end pr-8", "data-testid": "legend", children: seriesData.map((item, index) => (jsxRuntime.jsx(LegendItem, { color: item.color || chartColor(index), "data-testid": `legend-${item.name}`, label: item.name }, item.name))) }), jsxRuntime.jsx("div", { className: "flex w-full flex-1", children: jsxRuntime.jsx(Chart, { "data-testid": "bar-chart", onClick: onClick
-                        ? (e) => {
-                            onClick(e);
-                        }
-                        : undefined, options: {
-                        tooltip: {
-                            trigger: "item",
-                            confine: true,
-                            valueFormatter: value => `${value} ${units ?? ""}`,
-                        },
-                        grid: {
-                            left: "2%",
-                            right: "2%",
-                            bottom: "10%",
-                            top: "10%",
-                            containLabel: true,
-                        },
-                        xAxis: [
-                            {
-                                type: "category",
-                                axisLabel: {
-                                    formatter: value => {
-                                        if (isDateData(seriesData[0]?.data[0])) {
-                                            const date = formatDate(dateAndTimeUtils.toDateUtil(value), {
-                                                selectFormat: "dateOnly",
-                                                dateFormat: "medium",
-                                            });
-                                            return date.replace(",", ",\n");
-                                        }
-                                        return value;
-                                    },
-                                    fontSize: 10,
-                                    fontFamily: uiDesignTokens.fontFamily,
-                                    rotate: 45,
-                                    overflow: "truncate",
-                                },
-                                data: seriesData[0]?.data
-                                    .filter(({ value }) => Boolean(value))
-                                    .map(data => (isDateData(data) ? data.date : data.key)),
-                            },
-                        ],
-                        dataZoom: showDataZoom
-                            ? [
-                                {
-                                    type: "slider",
-                                    id: "insideX",
-                                    xAxisIndex: 0,
-                                    startValue: 0,
-                                    endValue: (seriesData[0]?.data.length ?? 0) > 10 ? 10 : (seriesData[0]?.data.length ?? 0),
-                                    showDetail: false,
-                                },
-                            ]
-                            : [],
-                        yAxis: [
-                            {
-                                type: "value",
-                                axisLabel: {
-                                    fontSize: 10,
-                                    fontFamily: uiDesignTokens.fontFamily,
-                                },
-                            },
-                        ],
-                        series: seriesData,
-                    }, showLoading: loading, style: { height: "100%", minHeight: "150px", width: "100%" } }) })] }));
-};
-const cvaChartRoot = cssClassVarianceUtilities.cvaMerge(["flex", "flex-col", "items-center", "h-full"]);
-
 exports.BarChart = BarChart;
 exports.Chart = Chart;
 exports.DonutChart = DonutChart;
 exports.EChart = EChart;
 exports.LegendItem = LegendItem;
 exports.useChartColor = useChartColor;
+exports.useChartNumberFormat = useChartNumberFormat;

package/index.esm.js

@@ -1,12 +1,12 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { Spinner, Text, useMergeRefs } from '@trackunit/react-components';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
+import { toDateUtil } from '@trackunit/date-and-time-utils';
+import { useLocale, useDateAndTime } from '@trackunit/react-date-and-time-hooks';
+import { DEFAULT_CHART_COLORS, CHART_STATUS_COLORS, fontFamily, DEFAULT_CHART_OTHER } from '@trackunit/ui-design-tokens';
+import { useRef, useCallback, useEffect, useMemo, useState } from 'react';
+import { Spinner, Text, useMergeRefs } from '@trackunit/react-components';
 import { objectKeys } from '@trackunit/shared-utils';
 import * as echarts from 'echarts';
-import { useRef, useCallback, useEffect, useMemo, useState } from 'react';
-import { DEFAULT_CHART_COLORS, CHART_STATUS_COLORS, DEFAULT_CHART_OTHER, fontFamily } from '@trackunit/ui-design-tokens';
-import { toDateUtil } from '@trackunit/date-and-time-utils';
-import { useDateAndTime } from '@trackunit/react-date-and-time-hooks';
 
 function isECElementEvent(value) {
     return (typeof value === "object" &&
@@ -282,6 +282,241 @@ const useChartColor = () => {
     }), [chartColor, chartColorArray, chartStatusColor]);
 };
 
+/**
+ * Locale-aware number formatting helpers for charts. Mirrors `useChartColor`:
+ * a hook that returns memoized formatting functions so chart consumers share one
+ * consistent compact-number style instead of hand-rolling `>= 1000 → k` logic.
+ *
+ * @returns {{ formatCompact: (value: number) => string }} An object exposing
+ * `formatCompact`, a locale-aware compact formatter (e.g. `40000 → "40K"`, `40_000_000 → "40M"`).
+ * @example Abbreviate a y-axis value
+ * ```tsx
+ * const { formatCompact } = useChartNumberFormat();
+ * formatCompact(40000); // "40K"
+ * ```
+ */
+const useChartNumberFormat = () => {
+    const locale = useLocale();
+    const formatCompact = useCallback((value) => new Intl.NumberFormat(locale, { notation: "compact", maximumFractionDigits: 1 }).format(value), [locale]);
+    return useMemo(() => ({ formatCompact }), [formatCompact]);
+};
+
+const DEFAULT_DATE_FORMAT = { selectFormat: "dateOnly", dateFormat: "medium" };
+const DEFAULT_ROTATE_LABELS = 45;
+const isDateData = (data) => !!data && "date" in data;
+const isEChartsTooltipParam = (param) => typeof param === "object" &&
+    param !== null &&
+    "seriesName" in param &&
+    typeof param.seriesName === "string" &&
+    "seriesIndex" in param &&
+    typeof param.seriesIndex === "number" &&
+    "dataIndex" in param &&
+    typeof param.dataIndex === "number" &&
+    "color" in param &&
+    typeof param.color === "string" &&
+    "marker" in param &&
+    typeof param.marker === "string";
+/**
+ * Create a BarChart with automatic legends and formatting. Built on top of the Chart component
+ * with sensible defaults for displaying categorical or time-series data.
+ *
+ * All customization props are optional and default to the component's original rendering, so
+ * existing usages are unaffected.
+ *
+ * ### When to use
+ * - To compare values across categories
+ * - To show trends over time with discrete intervals
+ * - When you need multiple series displayed side by side
+ *
+ * @example Bar chart with date-based data
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const UtilizationChart = () => (
+ *   <BarChart
+ *     series={{
+ *       name: "Utilization",
+ *       data: [
+ *         { date: "2024-01-01", value: 85 },
+ *         { date: "2024-01-02", value: 72 },
+ *         { date: "2024-01-03", value: 91 },
+ *       ],
+ *     }}
+ *     units="%"
+ *     onClick={(event) => console.log("Clicked bar:", event.data)}
+ *   />
+ * );
+ * ```
+ * @example Multi-series bar chart with data zoom
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const ComparisonChart = () => (
+ *   <BarChart
+ *     series={[
+ *       { name: "2023", color: "#3b82f6", data: [{ key: "Q1", value: 100 }, { key: "Q2", value: 120 }] },
+ *       { name: "2024", color: "#10b981", data: [{ key: "Q1", value: 130 }, { key: "Q2", value: 145 }] },
+ *     ]}
+ *     units="units"
+ *     showDataZoom={true}
+ *   />
+ * );
+ * ```
+ * @example Abbreviated y-axis, horizontal x-axis labels and a hidden legend
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const EmissionsChart = () => (
+ *   <BarChart
+ *     series={{ name: "Emissions", data: [{ key: "Excavator", value: 40000, color: "#3b82f6" }] }}
+ *     units="t"
+ *     yAxis={{ abbreviate: true }}
+ *     xAxis={{ rotateLabels: 0, formatLabel: (value) => value.slice(0, 10) }}
+ *     showLegend={false}
+ *   />
+ * );
+ * ```
+ * @example Custom tooltip from the typed payload
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const TrendChart = () => (
+ *   <BarChart
+ *     series={{ name: "Emissions", data: [{ date: "2024-01-01", value: 120 }] }}
+ *     tooltip={{
+ *       trigger: "axis",
+ *       formatter: ({ axisValue, entries }) =>
+ *         `${axisValue}<br/>${entries.map((e) => `${e.marker} ${e.seriesName}: ${e.value ?? 0}`).join("<br/>")}`,
+ *     }}
+ *   />
+ * );
+ * ```
+ * @param {BarChartProps} props - The props for the Chart component
+ * @returns {ReactElement} Chart component
+ */
+const BarChart = ({ series, loading = false, onClick, className, style, "data-testid": dataTestId, units, showDataZoom = false, xAxis, yAxis, tooltip, showLegend = true, ref, }) => {
+    const { formatDate } = useDateAndTime();
+    const { chartColor } = useChartColor();
+    const { formatCompact } = useChartNumberFormat();
+    const seriesData = useMemo(() => {
+        const seriesAsArray = Array.isArray(series) ? series : series !== undefined ? [series] : [];
+        return seriesAsArray.map((s, i) => ({
+            ...s,
+            color: s.color || chartColor(i),
+            type: "bar",
+            cursor: "arrow",
+            barGap: "0",
+            data: s.data.map(d => ({
+                ...d,
+                itemStyle: d.color ? { color: d.color } : undefined,
+            })),
+        }));
+    }, [series, chartColor]);
+    const yAxisLabelFormatter = useMemo(() => {
+        if (yAxis?.formatLabel) {
+            return yAxis.formatLabel;
+        }
+        if (yAxis?.abbreviate) {
+            return (value) => formatCompact(value);
+        }
+        return undefined;
+    }, [yAxis, formatCompact]);
+    const buildTooltipParams = useCallback((rawParams) => {
+        const params = Array.isArray(rawParams) ? rawParams : [rawParams];
+        const validParams = params.filter(isEChartsTooltipParam);
+        const firstParam = validParams[0];
+        const axisValueRaw = firstParam?.axisValue ?? firstParam?.name;
+        const axisValue = axisValueRaw === undefined ? "" : String(axisValueRaw);
+        const entries = validParams.map(param => {
+            const dataItem = seriesData[param.seriesIndex]?.data[param.dataIndex];
+            return {
+                seriesName: param.seriesName,
+                value: dataItem?.value,
+                color: param.color,
+                marker: param.marker,
+                dataIndex: param.dataIndex,
+                original: dataItem?.original,
+            };
+        });
+        return { axisValue, entries };
+    }, [seriesData]);
+    const tooltipTrigger = tooltip?.trigger ?? "item";
+    const tooltipFormatter = tooltip?.formatter;
+    const tooltipValueFormatter = tooltip?.formatValue;
+    return (jsxs("div", { className: cvaChartRoot$1({ className }), "data-testid": dataTestId, ref: ref, style: style, children: [showLegend ? (jsx("div", { className: "flex-0 flex flex-row gap-2 place-self-end pr-8", "data-testid": "legend", children: seriesData.map((item, index) => (jsx(LegendItem, { color: item.color || chartColor(index), "data-testid": `legend-${item.name}`, label: item.name }, item.name))) })) : null, jsx("div", { className: "flex w-full flex-1", children: jsx(Chart, { "data-testid": "bar-chart", onClick: onClick
+                        ? (e) => {
+                            onClick(e);
+                        }
+                        : undefined, options: {
+                        tooltip: {
+                            trigger: tooltipTrigger,
+                            confine: true,
+                            axisPointer: tooltipTrigger === "axis" ? { type: "shadow" } : undefined,
+                            formatter: tooltipFormatter
+                                ? (rawParams) => tooltipFormatter(buildTooltipParams(rawParams))
+                                : undefined,
+                            valueFormatter: tooltipFormatter
+                                ? undefined
+                                : value => tooltipValueFormatter && typeof value === "number"
+                                    ? tooltipValueFormatter(value)
+                                    : `${value} ${units ?? ""}`,
+                        },
+                        grid: {
+                            left: "2%",
+                            right: "2%",
+                            bottom: "10%",
+                            top: "10%",
+                            containLabel: true,
+                        },
+                        xAxis: [
+                            {
+                                type: "category",
+                                axisLabel: {
+                                    formatter: (value, index) => {
+                                        if (xAxis?.formatLabel) {
+                                            return xAxis.formatLabel(value, index);
+                                        }
+                                        if (isDateData(seriesData[0]?.data[0])) {
+                                            const date = formatDate(toDateUtil(value), xAxis?.dateFormat ?? DEFAULT_DATE_FORMAT);
+                                            return date.replace(",", ",\n");
+                                        }
+                                        return value;
+                                    },
+                                    fontSize: 10,
+                                    fontFamily,
+                                    rotate: xAxis?.rotateLabels ?? DEFAULT_ROTATE_LABELS,
+                                    overflow: "truncate",
+                                },
+                                data: seriesData[0]?.data.map(data => (isDateData(data) ? data.date : data.key)),
+                            },
+                        ],
+                        dataZoom: showDataZoom
+                            ? [
+                                {
+                                    type: "slider",
+                                    id: "insideX",
+                                    xAxisIndex: 0,
+                                    startValue: 0,
+                                    endValue: (seriesData[0]?.data.length ?? 0) > 10 ? 10 : (seriesData[0]?.data.length ?? 0),
+                                    showDetail: false,
+                                },
+                            ]
+                            : [],
+                        yAxis: [
+                            {
+                                type: "value",
+                                axisLabel: {
+                                    fontSize: 10,
+                                    fontFamily,
+                                    formatter: yAxisLabelFormatter,
+                                },
+                            },
+                        ],
+                        series: seriesData,
+                    }, showLoading: loading, style: { height: "100%", minHeight: "150px", width: "100%" } }) })] }));
+};
+const cvaChartRoot$1 = cvaMerge(["flex", "flex-col", "items-center", "h-full"]);
+
 /**
  * Limits the data set to the given limit.
  * If the data set is larger than the limit, the data set is limited to the limit and the rest of the data is added to the "Others" group.
@@ -487,9 +722,9 @@ const DonutChart = ({ data, size = "full", loading = false, onClick, className,
     if (loading) {
         return jsx(Spinner, { centering: "centered", "data-testid": dataTestId ? `${dataTestId}-loading` : "donut-chart-loading" });
     }
-    return (jsxs("div", { className: cvaChartRoot$1({ className }), "data-testid": dataTestId, ref: mergedRef, style: style, children: [jsx("div", { className: cvaChartContainer(), children: jsx(Chart, { className: cvaChart({ size }), "data-testid": dataTestId ? `chart-${dataTestId}` : undefined, onChartReady: handleChartReady, onClick: handleChartClick, onEvents: handleChartEvents, options: chartOptions, style: { width: "100%", height: "100%" } }) }), size === "full" && (jsx("div", { className: cvaLegend(), "data-testid": "legend", children: limitedData.map((item, index) => (jsx(LegendItem, { className: "p-1.5 py-0.5", color: item.color ?? chartColor(index), count: item.value, "data-testid": `legend-${item.id}`, disabled: (item.value ?? 0) === 0, hideValue: hideLegendValues, label: item.name, onClick: onClick ? () => onClick(item) : undefined, onMouseEnter: () => handleLegendMouseEnter(item), onMouseLeave: handleLegendMouseLeave, selected: item.selected, unit: unit }, item.id))) }))] }));
+    return (jsxs("div", { className: cvaChartRoot({ className }), "data-testid": dataTestId, ref: mergedRef, style: style, children: [jsx("div", { className: cvaChartContainer(), children: jsx(Chart, { className: cvaChart({ size }), "data-testid": dataTestId ? `chart-${dataTestId}` : undefined, onChartReady: handleChartReady, onClick: handleChartClick, onEvents: handleChartEvents, options: chartOptions, style: { width: "100%", height: "100%" } }) }), size === "full" && (jsx("div", { className: cvaLegend(), "data-testid": "legend", children: limitedData.map((item, index) => (jsx(LegendItem, { className: "p-1.5 py-0.5", color: item.color ?? chartColor(index), count: item.value, "data-testid": `legend-${item.id}`, disabled: (item.value ?? 0) === 0, hideValue: hideLegendValues, label: item.name, onClick: onClick ? () => onClick(item) : undefined, onMouseEnter: () => handleLegendMouseEnter(item), onMouseLeave: handleLegendMouseLeave, selected: item.selected, unit: unit }, item.id))) }))] }));
 };
-const cvaChartRoot$1 = cvaMerge([
+const cvaChartRoot = cvaMerge([
     "flex",
     "w-full",
     "h-full",
@@ -512,134 +747,4 @@ const cvaChart = cvaMerge(["flex-0", "max-w-[200px]", "max-h-[200px]", "place-se
 });
 const cvaLegend = cvaMerge(["flex", "overflow-auto", "justify-start", "flex-col", "flex-1"]);
 
-/**
- * Create a BarChart with automatic legends and formatting. Built on top of the Chart component
- * with sensible defaults for displaying categorical or time-series data.
- *
- * ### When to use
- * - To compare values across categories
- * - To show trends over time with discrete intervals
- * - When you need multiple series displayed side by side
- *
- * @example Bar chart with date-based data
- * ```tsx
- * import { BarChart } from "@trackunit/react-chart-components";
- *
- * const UtilizationChart = () => (
- *   <BarChart
- *     series={{
- *       name: "Utilization",
- *       data: [
- *         { date: "2024-01-01", value: 85 },
- *         { date: "2024-01-02", value: 72 },
- *         { date: "2024-01-03", value: 91 },
- *       ],
- *     }}
- *     units="%"
- *     onClick={(event) => console.log("Clicked bar:", event.data)}
- *   />
- * );
- * ```
- * @example Multi-series bar chart with data zoom
- * ```tsx
- * import { BarChart } from "@trackunit/react-chart-components";
- *
- * const ComparisonChart = () => (
- *   <BarChart
- *     series={[
- *       { name: "2023", color: "#3b82f6", data: [{ key: "Q1", value: 100 }, { key: "Q2", value: 120 }] },
- *       { name: "2024", color: "#10b981", data: [{ key: "Q1", value: 130 }, { key: "Q2", value: 145 }] },
- *     ]}
- *     units="units"
- *     showDataZoom={true}
- *   />
- * );
- * ```
- * @param {BarChartProps} props - The props for the Chart component
- * @returns {ReactElement} Chart component
- */
-const BarChart = ({ series, loading = false, onClick, className, style, "data-testid": dataTestId, units, showDataZoom = false, ref, }) => {
-    const { formatDate } = useDateAndTime();
-    const { chartColor } = useChartColor();
-    const seriesData = useMemo(() => {
-        const seriesAsArray = Array.isArray(series) ? series : series !== undefined ? [series] : [];
-        return seriesAsArray.map((s, i) => ({
-            ...s,
-            color: s.color || chartColor(i),
-            type: "bar",
-            cursor: "arrow",
-            barGap: "0",
-            data: s.data.map(d => ({
-                ...d,
-            })),
-        }));
-    }, [series, chartColor]);
-    const isDateData = (data) => !!data && "date" in data;
-    return (jsxs("div", { className: cvaChartRoot({ className }), "data-testid": dataTestId, ref: ref, style: style, children: [jsx("div", { className: "flex-0 flex flex-row gap-2 place-self-end pr-8", "data-testid": "legend", children: seriesData.map((item, index) => (jsx(LegendItem, { color: item.color || chartColor(index), "data-testid": `legend-${item.name}`, label: item.name }, item.name))) }), jsx("div", { className: "flex w-full flex-1", children: jsx(Chart, { "data-testid": "bar-chart", onClick: onClick
-                        ? (e) => {
-                            onClick(e);
-                        }
-                        : undefined, options: {
-                        tooltip: {
-                            trigger: "item",
-                            confine: true,
-                            valueFormatter: value => `${value} ${units ?? ""}`,
-                        },
-                        grid: {
-                            left: "2%",
-                            right: "2%",
-                            bottom: "10%",
-                            top: "10%",
-                            containLabel: true,
-                        },
-                        xAxis: [
-                            {
-                                type: "category",
-                                axisLabel: {
-                                    formatter: value => {
-                                        if (isDateData(seriesData[0]?.data[0])) {
-                                            const date = formatDate(toDateUtil(value), {
-                                                selectFormat: "dateOnly",
-                                                dateFormat: "medium",
-                                            });
-                                            return date.replace(",", ",\n");
-                                        }
-                                        return value;
-                                    },
-                                    fontSize: 10,
-                                    fontFamily,
-                                    rotate: 45,
-                                    overflow: "truncate",
-                                },
-                                data: seriesData[0]?.data
-                                    .filter(({ value }) => Boolean(value))
-                                    .map(data => (isDateData(data) ? data.date : data.key)),
-                            },
-                        ],
-                        dataZoom: showDataZoom
-                            ? [
-                                {
-                                    type: "slider",
-                                    id: "insideX",
-                                    xAxisIndex: 0,
-                                    startValue: 0,
-                                    endValue: (seriesData[0]?.data.length ?? 0) > 10 ? 10 : (seriesData[0]?.data.length ?? 0),
-                                    showDetail: false,
-                                },
-                            ]
-                            : [],
-                        yAxis: [
-                            {
-                                type: "value",
-                                axisLabel: {
-                                    fontSize: 10,
-                                    fontFamily,
-                                },
-                            },
-                        ],
-                        series: seriesData,
-                    }, showLoading: loading, style: { height: "100%", minHeight: "150px", width: "100%" } }) })] }));
-};
-const cvaChartRoot = cvaMerge(["flex", "flex-col", "items-center", "h-full"]);
-
-export { BarChart, Chart, DonutChart, EChart, LegendItem, useChartColor };
+export { BarChart, Chart, DonutChart, EChart, LegendItem, useChartColor, useChartNumberFormat };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-chart-components",
-  "version": "2.1.43-alpha-6a85feaada3.0",
+  "version": "2.1.43",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -9,12 +9,12 @@
   },
   "dependencies": {
     "echarts": "5.6.0",
-    "@trackunit/date-and-time-utils": "1.13.47-alpha-6a85feaada3.0",
-    "@trackunit/react-date-and-time-hooks": "2.1.42-alpha-6a85feaada3.0",
-    "@trackunit/ui-design-tokens": "1.13.44-alpha-6a85feaada3.0",
-    "@trackunit/shared-utils": "1.15.44-alpha-6a85feaada3.0",
-    "@trackunit/css-class-variance-utilities": "1.13.44-alpha-6a85feaada3.0",
-    "@trackunit/react-components": "2.1.40-alpha-6a85feaada3.0"
+    "@trackunit/date-and-time-utils": "1.13.46",
+    "@trackunit/react-date-and-time-hooks": "2.1.42",
+    "@trackunit/ui-design-tokens": "1.13.43",
+    "@trackunit/shared-utils": "1.15.43",
+    "@trackunit/css-class-variance-utilities": "1.13.43",
+    "@trackunit/react-components": "2.1.40"
   },
   "peerDependencies": {
     "@apollo/client": "^3.13.8",

package/src/BarChart/BarChart.d.ts

@@ -1,3 +1,4 @@
+import { type TemporalFormat } from "@trackunit/date-and-time-utils";
 import { CommonProps, Refable, type Styleable } from "@trackunit/react-components";
 import { ECElementEvent } from "echarts";
 import { ReactElement } from "react";
@@ -10,6 +11,10 @@ export interface BarChartData<TProps extends object = object> {
      * If selected, it'll be highlighted
      */
     selected?: boolean;
+    /**
+     * Per-bar color. Falls back to the series color / auto color when omitted.
+     */
+    color?: string;
     /**
      * Supply the original object that this chart data item was constructed from. It'll be available on callbacks
      */
@@ -32,6 +37,88 @@ export interface SeriesData<TProps extends object> {
     color?: string;
     data: Array<BarChartGenericData<TProps>> | Array<BarChartDateData<TProps>>;
 }
+/**
+ * A single entry in a tooltip payload. For `trigger: "item"` there is one entry;
+ * for `trigger: "axis"` there is one entry per series at the hovered category.
+ */
+export interface BarChartTooltipEntry<TProps extends object = object> {
+    /**
+     * The name of the series this entry belongs to
+     */
+    seriesName: string;
+    /**
+     * The numeric value of the hovered bar
+     */
+    value: number | undefined;
+    /**
+     * The resolved color of the bar
+     */
+    color: string;
+    /**
+     * The colored-dot marker HTML that ECharts provides
+     */
+    marker: string;
+    /**
+     * The index of the data item within its series
+     */
+    dataIndex: number;
+    /**
+     * The original object the data item was constructed from
+     */
+    original?: TProps;
+}
+/**
+ * Typed tooltip payload passed to `tooltip.formatter`.
+ */
+export interface BarChartTooltipParams<TProps extends object = object> {
+    /**
+     * The x-axis category/date value being hovered
+     */
+    axisValue: string;
+    /**
+     * One entry for `trigger: "item"`, one entry per series for `trigger: "axis"`
+     */
+    entries: Array<BarChartTooltipEntry<TProps>>;
+}
+export interface BarChartXAxisOptions {
+    /**
+     * Date granularity for date-based x-axis labels. Defaults to
+     * `{ selectFormat: "dateOnly", dateFormat: "medium" }`.
+     */
+    dateFormat?: TemporalFormat;
+    /**
+     * Full control over the x-axis label string. Wins over `dateFormat`.
+     */
+    formatLabel?: (value: string, index: number) => string;
+    /**
+     * Rotation of the x-axis labels in degrees. Defaults to `45`; `0` renders horizontal labels.
+     */
+    rotateLabels?: number;
+}
+export interface BarChartYAxisOptions {
+    /**
+     * Locale-aware compact y-axis labels (e.g. `40,000 → 40K`). Defaults to `false`.
+     */
+    abbreviate?: boolean;
+    /**
+     * Full control over the y-axis label string. Wins over `abbreviate`.
+     */
+    formatLabel?: (value: number) => string;
+}
+export interface BarChartTooltipOptions<TProps extends object = object> {
+    /**
+     * Format a single tooltip value. Defaults to `` `${value} ${units}` ``.
+     */
+    formatValue?: (value: number) => string;
+    /**
+     * Build the entire tooltip from a typed payload. Wins over `formatValue`.
+     */
+    formatter?: (params: BarChartTooltipParams<TProps>) => string;
+    /**
+     * Tooltip trigger mode. Defaults to `"item"`.
+     */
+    trigger?: "item" | "axis";
+}
 export interface BarChartProps<TProps extends object> extends CommonProps, Refable<HTMLDivElement>, Styleable {
     /**
      * Array of series of data points to show
@@ -53,11 +140,30 @@ export interface BarChartProps<TProps extends object> extends CommonProps, Refab
      * Show data zoom
      */
     showDataZoom?: boolean;
+    /**
+     * Curated x-axis customization (label formatting and rotation).
+     */
+    xAxis?: BarChartXAxisOptions;
+    /**
+     * Curated y-axis customization (label formatting and abbreviation).
+     */
+    yAxis?: BarChartYAxisOptions;
+    /**
+     * Curated tooltip customization (value/payload formatting and trigger mode).
+     */
+    tooltip?: BarChartTooltipOptions<TProps>;
+    /**
+     * Toggle the custom legend row. Defaults to `true`.
+     */
+    showLegend?: boolean;
 }
 /**
  * Create a BarChart with automatic legends and formatting. Built on top of the Chart component
  * with sensible defaults for displaying categorical or time-series data.
  *
+ * All customization props are optional and default to the component's original rendering, so
+ * existing usages are unaffected.
+ *
  * ### When to use
  * - To compare values across categories
  * - To show trends over time with discrete intervals
@@ -97,7 +203,36 @@ export interface BarChartProps<TProps extends object> extends CommonProps, Refab
  *   />
  * );
  * ```
+ * @example Abbreviated y-axis, horizontal x-axis labels and a hidden legend
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const EmissionsChart = () => (
+ *   <BarChart
+ *     series={{ name: "Emissions", data: [{ key: "Excavator", value: 40000, color: "#3b82f6" }] }}
+ *     units="t"
+ *     yAxis={{ abbreviate: true }}
+ *     xAxis={{ rotateLabels: 0, formatLabel: (value) => value.slice(0, 10) }}
+ *     showLegend={false}
+ *   />
+ * );
+ * ```
+ * @example Custom tooltip from the typed payload
+ * ```tsx
+ * import { BarChart } from "@trackunit/react-chart-components";
+ *
+ * const TrendChart = () => (
+ *   <BarChart
+ *     series={{ name: "Emissions", data: [{ date: "2024-01-01", value: 120 }] }}
+ *     tooltip={{
+ *       trigger: "axis",
+ *       formatter: ({ axisValue, entries }) =>
+ *         `${axisValue}<br/>${entries.map((e) => `${e.marker} ${e.seriesName}: ${e.value ?? 0}`).join("<br/>")}`,
+ *     }}
+ *   />
+ * );
+ * ```
  * @param {BarChartProps} props - The props for the Chart component
  * @returns {ReactElement} Chart component
  */
-export declare const BarChart: <TProps extends object>({ series, loading, onClick, className, style, "data-testid": dataTestId, units, showDataZoom, ref, }: BarChartProps<TProps>) => ReactElement;
+export declare const BarChart: <TProps extends object>({ series, loading, onClick, className, style, "data-testid": dataTestId, units, showDataZoom, xAxis, yAxis, tooltip, showLegend, ref, }: BarChartProps<TProps>) => ReactElement;

package/src/index.d.ts

@@ -1,6 +1,7 @@
+export * from "./BarChart/BarChart";
 export * from "./Chart/Chart";
 export * from "./DonutChart/DonutChart";
-export * from "./BarChart/BarChart";
+export * from "./EChart/EChart";
 export * from "./LegendItem/LegendItem";
 export * from "./utils/useChartColor";
-export * from "./EChart/EChart";
+export * from "./utils/useChartNumberFormat";

package/src/utils/useChartNumberFormat.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Locale-aware number formatting helpers for charts. Mirrors `useChartColor`:
+ * a hook that returns memoized formatting functions so chart consumers share one
+ * consistent compact-number style instead of hand-rolling `>= 1000 → k` logic.
+ *
+ * @returns {{ formatCompact: (value: number) => string }} An object exposing
+ * `formatCompact`, a locale-aware compact formatter (e.g. `40000 → "40K"`, `40_000_000 → "40M"`).
+ * @example Abbreviate a y-axis value
+ * ```tsx
+ * const { formatCompact } = useChartNumberFormat();
+ * formatCompact(40000); // "40K"
+ * ```
+ */
+export declare const useChartNumberFormat: () => {
+    formatCompact: (value: number) => string;
+};