@trackunit/react-chart-components 1.10.19 → 1.10.20

package/index.cjs.js

@@ -177,8 +177,48 @@ const EChart = ({ option, style, className, onChartReady, onClick, onEvents, not
 const cvaEChart = cssClassVarianceUtilities.cvaMerge(["w-full", "h-full"]);
 
 /**
- * The Chart component is a wrapper component for ECharts.
- * Handles events and click functionality.
+ * The Chart component is a wrapper component for ECharts, providing a simplified API for rendering interactive charts.
+ * It handles loading states, event callbacks, and timezone labels out of the box.
+ *
+ * ### When to use
+ * - When you need full control over ECharts configuration options
+ * - For custom or complex chart types not covered by specialized components (BarChart, DonutChart)
+ *
+ * ### When not to use
+ * - For standard bar or donut charts, use the dedicated BarChart or DonutChart components
+ *
+ * @example Basic line chart
+ * ```tsx
+ * import { Chart } from "@trackunit/react-chart-components";
+ *
+ * const LineChart = () => (
+ *   <Chart
+ *     options={{
+ *       xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
+ *       yAxis: { type: "value" },
+ *       series: [{ data: [150, 230, 224, 218, 135], type: "line" }],
+ *     }}
+ *     style={{ height: "300px" }}
+ *   />
+ * );
+ * ```
+ * @example Chart with loading state and click handler
+ * ```tsx
+ * import { Chart } from "@trackunit/react-chart-components";
+ *
+ * const InteractiveChart = ({ loading, data }) => (
+ *   <Chart
+ *     showLoading={loading}
+ *     loadingOption={{ text: "Loading chart data..." }}
+ *     onClick={(event) => console.log("Clicked:", event.data)}
+ *     options={{
+ *       xAxis: { type: "category", data: data.labels },
+ *       yAxis: { type: "value" },
+ *       series: [{ data: data.values, type: "bar" }],
+ *     }}
+ *   />
+ * );
+ * ```
  */
 const Chart = ({ options, showLoading = false, className, style, onChartReady, onClick, onEvents, merge = true, loadingOption, timezoneLabel, renderer = "canvas", "data-testid": dataTestId, }) => {
     const containerStyle = {
@@ -295,8 +335,49 @@ const useLimitDataSet = (data, limit, autoSortData = true, othersName) => {
 };
 
 /**
- * Create a DonutChart with legends based on our current Chart component
+ * Create a DonutChart with interactive legends. Shows proportional data with a center total
+ * and hover-to-highlight interactions between chart segments and legend items.
+ *
+ * ### When to use
+ * - To show parts of a whole (percentages, distributions)
+ * - When you have a limited number of categories (ideally 6 or fewer)
+ * - To display summary metrics with categorical breakdowns
  *
+ * ### When not to use
+ * - For comparing values across many categories (use BarChart)
+ * - For time-series data (use line or bar charts)
+ *
+ * @example Basic donut chart with categories
+ * ```tsx
+ * import { DonutChart } from "@trackunit/react-chart-components";
+ *
+ * const AssetDistribution = () => (
+ *   <DonutChart
+ *     data={[
+ *       { id: "excavators", name: "Excavators", value: 45, color: "#3b82f6" },
+ *       { id: "loaders", name: "Loaders", value: 30, color: "#10b981" },
+ *       { id: "trucks", name: "Trucks", value: 25, color: "#f59e0b" },
+ *     ]}
+ *     onClick={(item) => console.log("Selected:", item.name)}
+ *   />
+ * );
+ * ```
+ * @example Compact donut chart for dashboards
+ * ```tsx
+ * import { DonutChart } from "@trackunit/react-chart-components";
+ *
+ * const UtilizationDonut = () => (
+ *   <DonutChart
+ *     data={[
+ *       { id: "active", name: "Active", value: 75 },
+ *       { id: "idle", name: "Idle", value: 25 },
+ *     ]}
+ *     size="compact"
+ *     unit="%"
+ *     overrideTotal={75}
+ *   />
+ * );
+ * ```
  * @param {DonutChartProps} props - The props for the Chart component
  * @returns {ReactElement} Chart component
  */
@@ -452,8 +533,48 @@ 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 legends. Based on Chart component
+ * 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
  */

package/index.esm.js

@@ -156,8 +156,48 @@ const EChart = ({ option, style, className, onChartReady, onClick, onEvents, not
 const cvaEChart = cvaMerge(["w-full", "h-full"]);
 
 /**
- * The Chart component is a wrapper component for ECharts.
- * Handles events and click functionality.
+ * The Chart component is a wrapper component for ECharts, providing a simplified API for rendering interactive charts.
+ * It handles loading states, event callbacks, and timezone labels out of the box.
+ *
+ * ### When to use
+ * - When you need full control over ECharts configuration options
+ * - For custom or complex chart types not covered by specialized components (BarChart, DonutChart)
+ *
+ * ### When not to use
+ * - For standard bar or donut charts, use the dedicated BarChart or DonutChart components
+ *
+ * @example Basic line chart
+ * ```tsx
+ * import { Chart } from "@trackunit/react-chart-components";
+ *
+ * const LineChart = () => (
+ *   <Chart
+ *     options={{
+ *       xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
+ *       yAxis: { type: "value" },
+ *       series: [{ data: [150, 230, 224, 218, 135], type: "line" }],
+ *     }}
+ *     style={{ height: "300px" }}
+ *   />
+ * );
+ * ```
+ * @example Chart with loading state and click handler
+ * ```tsx
+ * import { Chart } from "@trackunit/react-chart-components";
+ *
+ * const InteractiveChart = ({ loading, data }) => (
+ *   <Chart
+ *     showLoading={loading}
+ *     loadingOption={{ text: "Loading chart data..." }}
+ *     onClick={(event) => console.log("Clicked:", event.data)}
+ *     options={{
+ *       xAxis: { type: "category", data: data.labels },
+ *       yAxis: { type: "value" },
+ *       series: [{ data: data.values, type: "bar" }],
+ *     }}
+ *   />
+ * );
+ * ```
  */
 const Chart = ({ options, showLoading = false, className, style, onChartReady, onClick, onEvents, merge = true, loadingOption, timezoneLabel, renderer = "canvas", "data-testid": dataTestId, }) => {
     const containerStyle = {
@@ -274,8 +314,49 @@ const useLimitDataSet = (data, limit, autoSortData = true, othersName) => {
 };
 
 /**
- * Create a DonutChart with legends based on our current Chart component
+ * Create a DonutChart with interactive legends. Shows proportional data with a center total
+ * and hover-to-highlight interactions between chart segments and legend items.
+ *
+ * ### When to use
+ * - To show parts of a whole (percentages, distributions)
+ * - When you have a limited number of categories (ideally 6 or fewer)
+ * - To display summary metrics with categorical breakdowns
  *
+ * ### When not to use
+ * - For comparing values across many categories (use BarChart)
+ * - For time-series data (use line or bar charts)
+ *
+ * @example Basic donut chart with categories
+ * ```tsx
+ * import { DonutChart } from "@trackunit/react-chart-components";
+ *
+ * const AssetDistribution = () => (
+ *   <DonutChart
+ *     data={[
+ *       { id: "excavators", name: "Excavators", value: 45, color: "#3b82f6" },
+ *       { id: "loaders", name: "Loaders", value: 30, color: "#10b981" },
+ *       { id: "trucks", name: "Trucks", value: 25, color: "#f59e0b" },
+ *     ]}
+ *     onClick={(item) => console.log("Selected:", item.name)}
+ *   />
+ * );
+ * ```
+ * @example Compact donut chart for dashboards
+ * ```tsx
+ * import { DonutChart } from "@trackunit/react-chart-components";
+ *
+ * const UtilizationDonut = () => (
+ *   <DonutChart
+ *     data={[
+ *       { id: "active", name: "Active", value: 75 },
+ *       { id: "idle", name: "Idle", value: 25 },
+ *     ]}
+ *     size="compact"
+ *     unit="%"
+ *     overrideTotal={75}
+ *   />
+ * );
+ * ```
  * @param {DonutChartProps} props - The props for the Chart component
  * @returns {ReactElement} Chart component
  */
@@ -431,8 +512,48 @@ 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 legends. Based on Chart component
+ * 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
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-chart-components",
-  "version": "1.10.19",
+  "version": "1.10.20",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -9,12 +9,12 @@
   "dependencies": {
     "echarts": "5.6.0",
     "react": "19.0.0",
-    "@trackunit/date-and-time-utils": "1.10.15",
-    "@trackunit/react-date-and-time-hooks": "1.10.19",
-    "@trackunit/ui-design-tokens": "1.10.15",
-    "@trackunit/shared-utils": "1.12.15",
-    "@trackunit/css-class-variance-utilities": "1.10.15",
-    "@trackunit/react-components": "1.14.18"
+    "@trackunit/date-and-time-utils": "1.10.16",
+    "@trackunit/react-date-and-time-hooks": "1.10.20",
+    "@trackunit/ui-design-tokens": "1.10.16",
+    "@trackunit/shared-utils": "1.12.16",
+    "@trackunit/css-class-variance-utilities": "1.10.16",
+    "@trackunit/react-components": "1.14.19"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/BarChart/BarChart.d.ts

@@ -55,8 +55,48 @@ export interface BarChartProps<TProps extends object> extends CommonProps {
     showDataZoom?: boolean;
 }
 /**
- * Create a BarChart with legends. Based on Chart component
+ * 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
  */

package/src/Chart/Chart.d.ts

@@ -59,7 +59,47 @@ export type ChartProps = CommonProps & {
     "data-testid"?: string;
 };
 /**
- * The Chart component is a wrapper component for ECharts.
- * Handles events and click functionality.
+ * The Chart component is a wrapper component for ECharts, providing a simplified API for rendering interactive charts.
+ * It handles loading states, event callbacks, and timezone labels out of the box.
+ *
+ * ### When to use
+ * - When you need full control over ECharts configuration options
+ * - For custom or complex chart types not covered by specialized components (BarChart, DonutChart)
+ *
+ * ### When not to use
+ * - For standard bar or donut charts, use the dedicated BarChart or DonutChart components
+ *
+ * @example Basic line chart
+ * ```tsx
+ * import { Chart } from "@trackunit/react-chart-components";
+ *
+ * const LineChart = () => (
+ *   <Chart
+ *     options={{
+ *       xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
+ *       yAxis: { type: "value" },
+ *       series: [{ data: [150, 230, 224, 218, 135], type: "line" }],
+ *     }}
+ *     style={{ height: "300px" }}
+ *   />
+ * );
+ * ```
+ * @example Chart with loading state and click handler
+ * ```tsx
+ * import { Chart } from "@trackunit/react-chart-components";
+ *
+ * const InteractiveChart = ({ loading, data }) => (
+ *   <Chart
+ *     showLoading={loading}
+ *     loadingOption={{ text: "Loading chart data..." }}
+ *     onClick={(event) => console.log("Clicked:", event.data)}
+ *     options={{
+ *       xAxis: { type: "category", data: data.labels },
+ *       yAxis: { type: "value" },
+ *       series: [{ data: data.values, type: "bar" }],
+ *     }}
+ *   />
+ * );
+ * ```
  */
 export declare const Chart: ({ options, showLoading, className, style, onChartReady, onClick, onEvents, merge, loadingOption, timezoneLabel, renderer, "data-testid": dataTestId, }: ChartProps) => ReactElement;

package/src/DonutChart/DonutChart.d.ts

@@ -91,8 +91,49 @@ export interface DonutChartProps<TProps extends object> extends CommonProps {
     othersName?: string;
 }
 /**
- * Create a DonutChart with legends based on our current Chart component
+ * Create a DonutChart with interactive legends. Shows proportional data with a center total
+ * and hover-to-highlight interactions between chart segments and legend items.
  *
+ * ### When to use
+ * - To show parts of a whole (percentages, distributions)
+ * - When you have a limited number of categories (ideally 6 or fewer)
+ * - To display summary metrics with categorical breakdowns
+ *
+ * ### When not to use
+ * - For comparing values across many categories (use BarChart)
+ * - For time-series data (use line or bar charts)
+ *
+ * @example Basic donut chart with categories
+ * ```tsx
+ * import { DonutChart } from "@trackunit/react-chart-components";
+ *
+ * const AssetDistribution = () => (
+ *   <DonutChart
+ *     data={[
+ *       { id: "excavators", name: "Excavators", value: 45, color: "#3b82f6" },
+ *       { id: "loaders", name: "Loaders", value: 30, color: "#10b981" },
+ *       { id: "trucks", name: "Trucks", value: 25, color: "#f59e0b" },
+ *     ]}
+ *     onClick={(item) => console.log("Selected:", item.name)}
+ *   />
+ * );
+ * ```
+ * @example Compact donut chart for dashboards
+ * ```tsx
+ * import { DonutChart } from "@trackunit/react-chart-components";
+ *
+ * const UtilizationDonut = () => (
+ *   <DonutChart
+ *     data={[
+ *       { id: "active", name: "Active", value: 75 },
+ *       { id: "idle", name: "Idle", value: 25 },
+ *     ]}
+ *     size="compact"
+ *     unit="%"
+ *     overrideTotal={75}
+ *   />
+ * );
+ * ```
  * @param {DonutChartProps} props - The props for the Chart component
  * @returns {ReactElement} Chart component
  */