pagamio-frontend-commons-lib/lib/dashboard-visuals/utils/formatUtil.d.ts

Pagamio library for Frontend reusable components like the form engine and table container

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 {};