@pagamio/frontend-commons-lib 0.8.175 → 0.8.183

package/lib/dashboard-visuals/utils/chartOptions.js

@@ -0,0 +1,393 @@
+import { formatDonutChartData } from '.';
+import { createTooltipFormatter } from './tooltipUtils';
+export const createDistributionMetricOptions = ({ distributionChartTooltip, distributionData, processedTooltipFields, xAxisDataValueKey, seriesDataValueKey, displaySymbol, }) => {
+    const { tooltipValueFormat, tooltipTitle, tooltipUnit, treeMapSegmentLabel } = distributionChartTooltip;
+    const currency = distributionData?.[0]?.currency;
+    const formattedData = formatDonutChartData(distributionData || [], xAxisDataValueKey, seriesDataValueKey);
+    const labelFormatter = (params) => {
+        const formattedValue = params.value.toLocaleString();
+        return `${params.name}\n${treeMapSegmentLabel}: ${formattedValue}`;
+    };
+    const tooltipFormatter = createTooltipFormatter(tooltipValueFormat, tooltipTitle, tooltipUnit, processedTooltipFields, distributionData || [], currency, displaySymbol);
+    return getLargeDatasetChartOptions({
+        data: {
+            legendData: [],
+            seriesData: formattedData.seriesData,
+        },
+        labelFormatter,
+        tooltipFormatter,
+    });
+};
+export const getGroupedChartOptions = ({ xAxisLabel, xAxisValueKey, rightYAxisValueKey, leftYAxisValueKey, chartToolTip, data, yAxisLabelFormatter, }) => ({
+    tooltip: {
+        trigger: 'axis',
+        axisPointer: { type: 'shadow' },
+        ...chartToolTip,
+    },
+    legend: {
+        data: ['Total Amount', 'Quantity Sold'],
+        top: 0,
+        textStyle: { fontSize: 12 },
+    },
+    grid: {
+        left: '3%',
+        right: '4%',
+        bottom: '3%',
+        containLabel: true,
+    },
+    xAxis: {
+        type: 'category',
+        name: xAxisLabel,
+        data: data.map((item) => item[xAxisValueKey]),
+        axisLabel: {
+            interval: 0,
+            rotate: 30,
+        },
+    },
+    yAxis: [
+        {
+            type: 'value',
+            name: 'Total Amount',
+            position: 'left',
+            axisLine: {
+                show: true,
+                lineStyle: { color: '#c789b8' },
+            },
+            axisLabel: {
+                formatter: yAxisLabelFormatter || ((value) => `${(value / 1000).toFixed(0)}k`),
+            },
+        },
+        {
+            type: 'value',
+            name: 'Quantity Sold',
+            position: 'right',
+            axisLine: {
+                show: true,
+                lineStyle: { color: '#5470c6' },
+            },
+        },
+    ],
+    series: [
+        {
+            name: 'Total Amount',
+            type: 'bar',
+            data: data.map((item) => item[leftYAxisValueKey]),
+            itemStyle: { color: '#c789b8' },
+        },
+        {
+            name: 'Quantity Sold',
+            type: 'bar',
+            yAxisIndex: 1,
+            data: data.map((item) => item[rightYAxisValueKey]),
+            itemStyle: { color: '#5470c6' },
+        },
+    ],
+    dataZoom: [
+        {
+            type: 'inside',
+            start: 0,
+            end: 100,
+        },
+    ],
+    responsive: true,
+    maintainAspectRatio: false,
+});
+export const getLineGraphOptions = ({ title, yAxisLabel, chartToolTip, data, yAxisLabelFormatter, }) => {
+    if (!data?.length)
+        return {};
+    return {
+        tooltip: {
+            trigger: 'axis',
+            ...chartToolTip,
+        },
+        legend: {
+            data: data.map((s) => s.name),
+            bottom: 0,
+        },
+        grid: {
+            left: '5%',
+            right: '5%',
+            bottom: '20%',
+            top: title ? '60' : '30',
+            containLabel: true,
+        },
+        xAxis: {
+            type: 'time',
+            axisLabel: {
+                formatter: (value) => {
+                    // value is a timestamp (ms since epoch)
+                    const dateObj = new Date(value);
+                    const day = dateObj.getDate();
+                    const month = dateObj.getMonth() + 1; // getMonth() is zero-based
+                    const hour = dateObj.getHours().toString().padStart(2, '0');
+                    const minute = dateObj.getMinutes().toString().padStart(2, '0');
+                    return `${day}/${month}-${hour}:${minute}`;
+                },
+                name: 'Date',
+                hideOverlap: true,
+            },
+            splitLine: {
+                show: false,
+            },
+        },
+        yAxis: {
+            type: 'value',
+            name: yAxisLabel,
+            axisLabel: {
+                formatter: yAxisLabelFormatter || ((value) => `${value}`),
+            },
+        },
+        series: data.map((series) => ({
+            type: 'line',
+            name: series.name,
+            data: series.data.map((point) => ({
+                value: [point.date instanceof Date ? point.date : new Date(point.date), point.value],
+            })),
+            showSymbol: true,
+        })),
+    };
+};
+export const getChartBarOptions = ({ title, colorScheme = ['#60A5FA', '#93C5FD'], yAxisDataNameKey, xAxisNameKey, xAxisLabel = '', yAxisLabel = '', chartToolTip, data, }) => ({
+    tooltip: {
+        trigger: 'axis',
+        axisPointer: {
+            type: 'shadow',
+        },
+        ...chartToolTip,
+    },
+    grid: {
+        left: '3%',
+        right: '4%',
+        bottom: '3%',
+        top: title ? '60' : '3%',
+        containLabel: true,
+    },
+    xAxis: {
+        type: 'value',
+        name: xAxisLabel,
+        axisLine: {
+            show: true,
+        },
+        axisTick: {
+            show: true,
+        },
+        splitLine: {
+            show: true,
+            lineStyle: {
+                color: '#E5E7EB',
+            },
+        },
+    },
+    yAxis: {
+        type: 'category',
+        name: yAxisLabel,
+        data: data.map((item) => item[yAxisDataNameKey]).reverse(), // Reverse the categories to maintain original order
+        axisLabel: {
+            formatter: (value) => {
+                return value.length > 20 ? `${value.substring(0, 17)}...` : value;
+            },
+        },
+    },
+    series: [
+        {
+            name: 'Value',
+            type: 'bar',
+            data: data.map((item) => item[xAxisNameKey]).reverse(), // Reverse the data to match categories
+            itemStyle: {
+                color: {
+                    type: 'linear',
+                    x: 0,
+                    y: 0,
+                    x2: 1,
+                    y2: 0,
+                    colorStops: [
+                        {
+                            offset: 0,
+                            color: colorScheme[0],
+                        },
+                        {
+                            offset: 1,
+                            color: colorScheme[1],
+                        },
+                    ],
+                },
+            },
+            barWidth: '60%',
+            emphasis: {
+                itemStyle: {
+                    opacity: 0.8,
+                },
+            },
+        },
+    ],
+    aria: {
+        enabled: true,
+    },
+    animation: true,
+    animationDuration: 1000,
+    animationEasing: 'cubicInOut',
+});
+export const getDonutChartOptions = ({ data }) => {
+    const chartOptions = {
+        tooltip: {
+            trigger: 'item',
+            formatter: '{a} <br/>{b}: {c} ({d}%)',
+        },
+        legend: {
+            orient: 'horizontal',
+            bottom: 0,
+            left: 'center',
+        },
+        series: [
+            {
+                name: 'Distribution',
+                type: 'pie',
+                radius: ['40%', '70%'],
+                avoidLabelOverlap: false,
+                itemStyle: {
+                    borderRadius: 10,
+                    borderColor: '#fff',
+                    borderWidth: 2,
+                },
+                label: {
+                    show: true,
+                    position: 'outside',
+                    formatter: '{b}',
+                    fontSize: 12,
+                    lineHeight: 15,
+                    rich: {
+                        b: {
+                            fontSize: 12,
+                            lineHeight: 15,
+                        },
+                    },
+                },
+                labelLine: {
+                    show: true,
+                    length: 15,
+                    length2: 10,
+                },
+                emphasis: {
+                    label: {
+                        show: true,
+                        fontSize: 14,
+                        fontWeight: 'bold',
+                    },
+                    itemStyle: {
+                        shadowBlur: 10,
+                        shadowOffsetX: 0,
+                        shadowColor: 'rgba(0, 0, 0, 0.5)',
+                    },
+                },
+                data: data,
+            },
+        ],
+    };
+    return chartOptions;
+};
+export const formatChartLabel = (params) => {
+    console.log('formatChartLabel params', params);
+    const formattedValue = params.value.toLocaleString();
+    const percentage = params.treeMapPercent ? ` (${params.treeMapPercent.toFixed(1)}%)` : '';
+    return `${params.name}\n${params.valueLabel}: ${formattedValue}\n${percentage}`;
+};
+export const getLargeDatasetChartOptions = ({ data, labelFormatter, tooltipFormatter }) => {
+    return {
+        tooltip: {
+            trigger: 'item',
+            formatter: tooltipFormatter,
+        },
+        toolbox: {
+            show: true,
+            feature: {
+                dataView: {
+                    show: true,
+                    title: 'View as Text',
+                    readOnly: true,
+                    lang: ['Data View', 'Close', 'Refresh'],
+                },
+                saveAsImage: {
+                    show: true,
+                    title: 'Save Image',
+                },
+            },
+            right: '3%',
+            top: 5,
+        },
+        grid: {
+            left: '5%',
+            right: '5%',
+            bottom: '15%',
+            containLabel: true,
+        },
+        series: [
+            {
+                type: 'treemap',
+                data: data.seriesData,
+                label: {
+                    show: true,
+                    formatter: labelFormatter,
+                    position: 'inside',
+                },
+                breadcrumb: {
+                    show: false,
+                },
+                roam: 'scale',
+                nodeClick: false,
+                animation: true,
+                height: '85%',
+                itemStyle: {
+                    borderColor: '#fff',
+                    borderWidth: 1,
+                    gapWidth: 1,
+                },
+                emphasis: {
+                    itemStyle: {
+                        shadowBlur: 10,
+                        shadowOffsetX: 0,
+                        shadowColor: 'rgba(0, 0, 0, 0.5)',
+                    },
+                },
+                levels: [
+                    {
+                        itemStyle: {
+                            borderColor: '#fff',
+                            borderWidth: 1,
+                            gapWidth: 1,
+                        },
+                        upperLabel: {
+                            show: false,
+                        },
+                    },
+                ],
+            },
+        ],
+        dataZoom: [
+            {
+                type: 'slider',
+                show: true,
+                start: 0,
+                end: 100,
+                height: 20,
+                bottom: 10,
+                left: '5%',
+                right: '5%',
+                zoomLock: false,
+                showDetail: true,
+                borderColor: '#ccc',
+                borderRadius: 3,
+                backgroundColor: '#f5f5f5',
+                fillerColor: 'rgba(167, 183, 204, 0.4)',
+                handleIcon: 'M10.7,11.9v-1.3H9.3v1.3c-4.9,0.3-8.8,4.4-8.8,9.4c0,5,3.9,9.1,8.8,9.4v1.3h1.3v-1.3c4.9-0.3,8.8-4.4,8.8-9.4C19.5,16.3,15.6,12.2,10.7,11.9z M13.3,24.4H6.7V23h6.6V24.4z M13.3,19.6H6.7v-1.4h6.6V19.6z',
+                handleSize: '80%',
+                handleStyle: {
+                    color: '#fff',
+                    shadowBlur: 3,
+                    shadowColor: 'rgba(0, 0, 0, 0.6)',
+                    shadowOffsetX: 2,
+                    shadowOffsetY: 2,
+                },
+            },
+        ],
+    };
+};

package/lib/dashboard-visuals/utils/chunkArray.d.ts

@@ -0,0 +1 @@
+export declare const chunkArray: (array: any[], size: number) => any[][];

package/lib/dashboard-visuals/utils/chunkArray.js

@@ -0,0 +1,7 @@
+export const chunkArray = (array, size) => {
+    const result = [];
+    for (let i = 0; i < array.length; i += size) {
+        result.push(array.slice(i, i + size));
+    }
+    return result;
+};

package/lib/dashboard-visuals/utils/defaultColors.d.ts

@@ -0,0 +1 @@
+export declare const defaultColors: string[];

package/lib/dashboard-visuals/utils/defaultColors.js

@@ -0,0 +1 @@
+export const defaultColors = ['#5470c6', '#92cc76', '#c789b7', 'rgb(234, 217, 239)'];

package/lib/dashboard-visuals/utils/formatUtil.d.ts

@@ -0,0 +1,203 @@
+import { type MRT_ColumnDef } from 'mantine-react-table';
+import type { MetricData, TableColumn } from '../types';
+import type { DataPoint } from '../visuals/DistributionChart';
+interface SeriesItem {
+    name: string;
+    type: string;
+    stack: string;
+    data: number[];
+}
+interface ChartDataResult {
+    xAxisValues: string[];
+    seriesData: SeriesItem[];
+}
+type DateInput = string | Date | null | undefined;
+interface DateFormatOptions {
+    locale?: string;
+    fallback?: string;
+    includeTime?: boolean;
+}
+interface DateRangeFormatOptions extends DateFormatOptions {
+    separator?: string;
+}
+/**
+ * A generic utility to build x-axis values and series data for a stacked bar chart in ECharts.
+ *
+ * @param data - An array of objects of any shape (T).
+ * @param xAxisDataValueKey - The string key in each object representing x-axis data (e.g. "channel", "status").
+ * @param seriesDataNameKey - The string key in each object representing the series name (e.g. "productName").
+ * @param seriesDataValueKey - The string key in each object representing the numeric value (e.g. "amount").
+ *
+ * @returns An object containing:
+ *   - xAxisValues: A string[] of unique x-axis values (in order).
+ *   - seriesData: An array of SeriesItem (with "name", "type", "stack", and the numeric data array).
+ */
+export declare function getBarChartData<T extends Record<string, any>>(data: {
+    [key: string]: any;
+}[], xAxisDataValueKey: string, seriesDataNameKey: string, seriesDataValueKey: string): ChartDataResult;
+/**
+ * Flattens your data (if it happens to be an array of arrays)
+ * and maps it into an xAxis array of names and a seriesData
+ * array of { name, value } objects.
+ *
+ * @param data     The raw data from the backend, e.g. [ [ { amount: 60, productName: 'Electronics' }, ... ] ]
+ *                 If data is just a single array (e.g. [ { amount: 60, productName: 'Electronics' }, ... ]),
+ *                 this function will still work (no harm in calling `flat()`).
+ * @param nameKey  The key in each object that maps to the category name (used in xAxis and the `name` field).
+ * @param valueKey The key in each object that maps to the numeric value (used in `value`).
+ *
+ * @returns An object containing:
+ *          - xAxis: string[]   (e.g. ["Electronics", "Fashion", "Home & Garden"])
+ *          - seriesData: Array<{ name: string; value: number }>
+ *            (e.g. [{ name: "Electronics", value: 60 }, ...])
+ */
+export declare function getPieChartData<T extends Record<PropertyKey, any>>(data: T[] | T[][], // can be an array of objects OR an array of arrays of objects
+nameKey: keyof T, // e.g. 'productName'
+valueKey: keyof T, // e.g. 'amount'
+otherKey?: keyof T): {
+    xAxis: string[];
+    seriesData: {
+        name: string;
+        value: number;
+        otherValue: string | number;
+    }[];
+};
+/**
+ * Flattens your data (if it happens to be an array of arrays)
+ * and maps it into an xAxis array of names and a seriesData
+ * array of { name, value } objects.
+ *
+ * @param data     The raw data from the backend, e.g. [ [ { amount: 60, productName: 'Electronics' }, ... ] ]
+ *                 If data is just a single array (e.g. [ { amount: 60, productName: 'Electronics' }, ... ]),
+ *                 this function will still work (no harm in calling `flat()`).
+ * @param nameKey  The key in each object that maps to the category name (used in xAxis and the `name` field).
+ * @param valueKey The key in each object that maps to the numeric value (used in `value`).
+ *
+ * @returns An object containing:
+ *          - seriesData: Array<{ name: string; value: number }>
+ *            (e.g. [{ name: "Electronics", value: 60 }, ...])
+ */
+export declare function getSeriesData<T extends Record<PropertyKey, any>>(data: T[] | T[][], // can be an array of objects OR an array of arrays of objects
+nameKey: keyof T, // e.g. 'productName'
+valueKey: keyof T): {
+    seriesData: {
+        name: string;
+        value: number;
+    }[];
+};
+/**
+ * Flattens your data (if it happens to be an array of arrays)
+ * and maps it into a select options array. Handles null/undefined values safely.
+ *
+ * @param data      The raw data from the backend.
+ * @param labelKey  The key in each object that maps to the label in the options.
+ * @param valueKey  Optional key for the value in the options. If not provided, labelKey will be used for both label and value.
+ * @returns An object containing optionsData array with { label, value } pairs.
+ */
+export declare function getFilterOptionsData<T extends Record<PropertyKey, any>>(data: T[] | T[][], labelKey: keyof T, valueKey?: keyof T): {
+    optionsData: {
+        label: string;
+        value: string;
+    }[];
+};
+/**
+ * Flattens your data (if it happens to be an array of arrays)
+ * and maps it into a select options array.
+ */
+export declare function generateSelectOptions<T extends Record<PropertyKey, any>>(data: T[] | T[][], labelKey: keyof T, valueKey: keyof T): {
+    optionsData: {
+        label: string;
+        value: string;
+    }[];
+};
+export declare const formatValue: (value: number, format?: string, options?: {
+    currency?: string;
+    locale?: string;
+}) => string;
+/**
+ * Standardized date formatting function for the entire application.
+ * Formats dates to a consistent locale-specific format.
+ *
+ * @param date - Date string, Date object, or null/undefined
+ * @param options - Optional formatting options
+ * @returns Formatted date string or fallback value
+ */
+export declare const formatDate: (date: DateInput, options?: DateFormatOptions) => string;
+/**
+ * Formats a date range as a string.
+ *
+ * @param startDate - Start date
+ * @param endDate - End date
+ * @param options - Optional formatting options
+ * @returns Formatted date range string
+ */
+export declare const formatDateRange: (startDate: DateInput, endDate: DateInput, options?: DateRangeFormatOptions) => string;
+type IdInput = string | number | null | undefined;
+interface IdTruncateOptions {
+    /** Number of characters to show from the start (default: 5) */
+    startChars?: number;
+    /** Number of characters to show from the end (default: 5) */
+    endChars?: number;
+    /** Separator between start and end (default: '…') */
+    separator?: string;
+    /** Minimum length before truncation occurs (default: 10) */
+    minLength?: number;
+    /** Fallback value for null/undefined/empty values (default: '') */
+    fallback?: string;
+}
+/**
+ * Truncates long IDs to show first N and last N characters with a separator.
+ *
+ * @param id - ID string, number, or null/undefined
+ * @param options - Optional truncation options
+ * @returns Truncated ID string or fallback value
+ */
+export declare const truncateId: (id: IdInput, options?: IdTruncateOptions) => string;
+export declare const transformColumns: <TData extends Record<string, any>>(columns: TableColumn<TData>[]) => MRT_ColumnDef<TData>[];
+/**
+ * Formats an array of objects into DataPoint format required for Distribution Chart
+ * @param data Array of objects to format
+ * @param valueKey Key in the object to use as the value
+ * @param nameKey Key in the object to use as the name
+ * @returns Array of DataPoint objects
+ */
+export declare function formatToDataPoints<T extends Record<string, any>>(data: T[], valueKey: keyof T, nameKey: keyof T): DataPoint[];
+export declare const formatDonutChartData: (data: MetricData[], nameKey: string, valueKey: string) => {
+    legendData: any[];
+    seriesData: Record<string, any>[];
+};
+/**
+ * Transforms flat data into heatmap format with proper axis categories and data matrix.
+ *
+ * @param data - Array of objects containing the data
+ * @param xAxisKey - Key for x-axis categories (e.g., 'region', 'dayOfWeek')
+ * @param yAxisKey - Key for y-axis categories (e.g., 'product', 'hour')
+ * @param valueKey - Key for the numeric values to be displayed as heat intensity
+ * @returns Object with xAxis categories, yAxis categories, and heatmap data matrix
+ */
+export declare function getHeatmapData<T extends Record<string, any>>(data: T[], xAxisKey: keyof T, yAxisKey: keyof T, valueKey: keyof T): {
+    xAxis: string[];
+    yAxis: string[];
+    data: [number, number, number][];
+};
+/**
+ * Transforms date-based data into a day-of-week vs week heatmap format.
+ * Generic utility that can be used for any date field and value combination.
+ *
+ * This function supports two calling patterns:
+ * 1. Direct usage: createDayWeekHeatmapData(data, dateKey, valueKey)
+ * 2. HeatmapChart adapter: createDayWeekHeatmapData(data, xAxisKey, yAxisKey, valueKey)
+ *    - In this case, yAxisKey is used as the date field, xAxisKey is ignored
+ *
+ * @param data - Array of objects containing date and value data
+ * @param dateKeyOrXAxisKey - Key for the date field, or xAxisKey (ignored in 4-param version)
+ * @param valueKeyOrYAxisKey - Key for values, or yAxisKey (used as date field in 4-param version)
+ * @param optionalValueKey - Optional valueKey (used in 4-param version)
+ * @returns Object with day-of-week x-axis, week y-axis, and heatmap data matrix
+ */
+export declare function createDayWeekHeatmapData<T extends Record<string, any>>(data: T[], dateKeyOrXAxisKey: keyof T | string, valueKeyOrYAxisKey: keyof T | string, optionalValueKey?: keyof T | string): {
+    xAxis: string[];
+    yAxis: string[];
+    data: [number, number, number][];
+};
+export {};